@bitpal/checkout 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to `@bitpal/checkout`. Versions follow [semver](https://semver.org/) (pre-1.0: a minor bump may contain breaking changes, called out below).
+
+Source of truth: the BitPal monorepo (`packages/checkout-sdk`). The public repo `superlabs-x/bitpal-checkout-sdk` mirrors it.
+
+## 0.12.0 — 2026-11-06
+
+Merges the x402 line (0.8.0–0.11.0, previously released from the standalone repo) with the checkout API alignment fixes made in the monorepo.
+
+### Breaking (types)
+- `CreatePriceParams.currency` removed. The API always rejected it — a Price's currency is derived from `token_symbol` (`'USDC' | 'USDT' | 'JPYC'`, default `'USDC'`). Code that passed `currency` got a `400`; pass `token_symbol` instead.
+
+### Added
+- `PublicSession.pay_amount` — the exact amount the buyer must send, in the pay token's atomic units (`token_decimals`).
+- `BitPalError` now carries structured fields parsed from the API error body: `code`, `apiMessage`, `retryable`, `traceId`. `error.message` is unchanged from 0.11 (it is still the body's `error` value), so existing `catch` code keeps working. Also exported: `parseApiErrorBody`, `BitPalErrorDetails`.
+- `CreateSessionParams.expires_in_minutes` (1–60, default 15) — the session payment window.
+- Non-JSON error responses (e.g. an HTML `502` from a gateway) now throw `BitPalError` with `HTTP <status>` instead of a `SyntaxError`.
+
+### Fixed
+- **Session expiry was silently ignored.** `expires_in_seconds` was never an API field, so every session used the 15-minute default. The SDK now sends `expires_in_minutes`; `expires_in_seconds` is deprecated and converted (rounded up to whole minutes, 60–3600 s). Out-of-range values throw before the request.
+- `payer_wallet` and `pay_asset` on `createSession` are deprecated and no longer sent — the API never accepted them (it dropped them silently).
+- A contract test checks every SDK request (method, path, query and body keys) against the API's generated OpenAPI spec, so SDK ↔ API drift like the two above fails CI.
+
+### Fixed (docs / type comments)
+- `amount_total` is **always canonical 6-decimal**, regardless of the pay token. Only `amount_received`, `pay_amount` and the issued `expectedAmount` use `token_decimals`. (0.11 said `amount_total` used token decimals — wrong for 18-decimal tokens.)
+- Line item / Price `amount` is quoted in the line item's `currency` (`USDC`/`USDT` = USD, `JPYC` = JPY, no FX), not always USD.
+- Browser use: only `getPublicSession` may be called from a merchant's browser (CORS). Call `issueDepositAddress` / `getStatus` through your backend.
+- README: `previewFee` example now passes a human amount (`'29.00'`) — 0.11's README passed an atomic value, which the API reads as a human amount (1,000,000× too large).
+- README: full payments after the deadline (up to 7 days) are accepted as late payments (`late: true` on `checkout.session.paid`), not refunded.
+
+## 0.11.0 — 2026-09-17
+- **Breaking (x402 payer):** standard x402 payload — one EIP-3009 authorization and one signature (`{ signature, authorization }`). Fee split is committed by the `payTo` forwarder address. Old two-signature headers get a fresh `402`.
+- `paymentRequirements` carries the merchant wallet.
+
+## 0.10.0 — 2026-09-17
+- Webhook event `x402.payment.resolved` (an x402 payment left unresolved by `/settle` was later settled on-chain).
+
+## 0.9.0 — 2026-09-17
+- **Breaking:** `x402({ amount })` and `previewFee(amount)` take a human amount (`'1.00'`); use `amountAtomic` / `{ amountAtomic }` for raw values.
+
+## 0.8.0 — 2026-09-16
+- `x402()` per-call payment middleware, `createX402Payment()` payer helper, `X402ReplayStore` (memory default; pass a shared store when running several instances).
+
+## 0.7.0 — 2026-07-30
+- `allowed_assets: { chain, token }[]` as the standard way to set payment options.
+
+## 0.6.0 — 2026-07-30
+- Human `amount` input for line items and Prices; `paymentLinks` resource.
+
+## 0.5.0 — 2026-07-23
+- Initial public release: sessions, per-order deposit addresses, status polling, timestamped webhook signatures.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 BitPal
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 BitPal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,23 +13,28 @@ pnpm add @bitpal/checkout
 
 ## Amounts — just pass a human number
 
-Use **`amount`** in line items — a plain USD string like `"20"`, `"0.5"`, `"29.00"`. No decimals to compute.
+Use **`amount`** in line items — a plain decimal string like `"20"`, `"0.5"`, `"29.00"`. No decimals to compute.
 
 ```ts
 line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }]
 ```
 
-**The amount is a USD price — it does NOT depend on the chain or token decimals.** Whether the buyer pays with USDC (6dp) on Base or USDT (18dp) on BNB, you pass the same `amount`. BitPal rescales to the buyer's chosen token at deposit time. So you never compute per-token decimals. (Prices via `prices.create` take the same `amount`.)
+**The amount is quoted in the line item's `currency` — it does NOT depend on the chain or token decimals.** `currency: 'USDC'` / `'USDT'` means a USD price; `currency: 'JPYC'` means a JPY price (`amount: '1500'` → 1,500 JPYC — there is no FX conversion). Whether the buyer pays USDC (6dp) on Base or USDT (18dp) on BNB, you pass the same `amount`; BitPal rescales to the buyer's chosen token at deposit time. (Prices via `prices.create` take the same `amount`; their currency comes from `token_symbol`.)
 
 <details><summary>Advanced: raw atomic amounts</summary>
 
-If you already hold **atomic μUSD integer strings** ($1 = `"1000000"`), pass `amount_atomic` instead (mutually exclusive with `amount`):
+If you already hold **canonical 6-decimal integer strings** (`"1"` = `"1000000"`), pass `amount_atomic` instead (mutually exclusive with `amount`):
 
 ```
-$1.00 → "1000000"   $29.00 → "29000000"   $0.50 → "500000"
+1.00 → "1000000"   29.00 → "29000000"   0.50 → "500000"
 ```
 
-Helpers for atomic conversion (e.g. reading `amount_total` back): `toAtomic(v, decimals)` / `fromAtomic(v, decimals)` — read `decimals` from `payment_options[]`/`token_decimals` (6 for USDC/USDT, 18 for BNB USDT). `toAtomicUSDC`/`fromAtomicUSDC` are 6dp shortcuts.
+Reading amounts back:
+
+- `amount_total` is **always canonical 6dp**, whatever token the buyer pays with — `fromAtomic(amount_total, 6)`.
+- `amount_received`, `pay_amount` (the exact amount the buyer must send) and the issued `expectedAmount` are in the **pay token's units** — use `token_decimals` (6 for USDC/USDT, 18 for BNB USDT / JPYC). Never assume 6dp for these.
+
+Helpers: `toAtomic(v, decimals)` / `fromAtomic(v, decimals)`; `toAtomicUSDC`/`fromAtomicUSDC` are 6dp shortcuts.
 </details>
 
 ## Environments
@@ -73,7 +78,7 @@ const { data: session } = await bitpal.checkout.createSession({
     { chain: 'tron',   token: 'USDT' },
     { chain: 'solana', token: 'USDC' },
   ],
-  expires_in_seconds: 1800,
+  expires_in_minutes: 30,
   success_url: 'https://yourstore.com/thanks',
 });
 
@@ -96,6 +101,10 @@ The buyer then sends the exact amount from **any wallet or exchange** — no wal
 signature; they pay their own network gas. A watcher detects the deposit and a keeper sweeps it to
 you.
 
+> **Call this from your backend.** Browsers on your own domain can only call `getPublicSession`
+> directly (CORS). Proxy `issueDepositAddress` / `getStatus` through your server — and never ship a
+> secret key to the browser.
+
 ```ts
 const { data } = await bitpal.checkout.issueDepositAddress(session.id, {
   session_token: session.session_token!, // from createSession
@@ -106,11 +115,13 @@ const { data } = await bitpal.checkout.issueDepositAddress(session.id, {
 });
 
 console.log(data.depositAddress);  // buyer sends the exact amount here
-console.log(data.expectedAmount);  // atomic μUSDC — display this exact amount
+console.log(data.expectedAmount);  // atomic, in the pay token's decimals — display this exact amount
 ```
 
-> `refundAddress` is committed into the deposit address and **cannot change** after issuance
-> (over / under / late payments auto-refund there on-chain).
+> `refundAddress` is committed into the deposit address and **cannot change** after issuance.
+> Overpaid excess, wrong tokens, and underpayments left at expiry are refunded there on-chain. A full
+> payment that arrives after the deadline (up to 7 days) is accepted as a **late payment** — the
+> `checkout.session.paid` webhook carries `late: true` so you can decide how to fulfil it.
 
 ### Poll status (buyer UX)
 
@@ -124,8 +135,9 @@ Polling is for buyer-facing UX. For **server-side** confirmation, trust the webh
 ### Preview the fee
 
 ```ts
-const { data: fee } = await bitpal.checkout.previewFee(toAtomicUSDC('29.00'));
-console.log(fromAtomicUSDC(fee.fee_amount)); // e.g. "0.43"
+const { data: fee } = await bitpal.checkout.previewFee('29.00');            // human amount
+// or: await bitpal.checkout.previewFee({ amountAtomic: '29000000' });       // raw 6dp
+console.log(fromAtomicUSDC(fee.fee_amount)); // response is atomic — e.g. "0.43"
 ```
 
 ## Webhooks

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(index_exports, {
   fromAtomic: () => fromAtomic,
   fromAtomicUSDC: () => fromAtomicUSDC,
   normalizeSignature: () => normalizeSignature,
+  parseApiErrorBody: () => parseApiErrorBody,
   parseWebhookEvent: () => parseWebhookEvent,
   toAtomic: () => toAtomic,
   toAtomicUSDC: () => toAtomicUSDC,
@@ -138,12 +139,25 @@ var PaymentLinksResource = class {
 };
 
 // src/client.ts
+var EXPIRY_MIN_MINUTES = 1;
+var EXPIRY_MAX_MINUTES = 60;
+function resolveExpiryMinutes(minutes, seconds) {
+  if (minutes !== void 0 && seconds !== void 0) {
+    throw new Error("[BitPal] pass only one of `expires_in_minutes` or `expires_in_seconds`.");
+  }
+  const resolved = seconds !== void 0 ? Math.ceil(seconds / 60) : minutes;
+  if (resolved === void 0) return void 0;
+  if (!Number.isInteger(resolved) || resolved < EXPIRY_MIN_MINUTES || resolved > EXPIRY_MAX_MINUTES) {
+    throw new Error(`[BitPal] session expiry must be ${EXPIRY_MIN_MINUTES}\u2013${EXPIRY_MAX_MINUTES} minutes (expires_in_minutes) \u2014 got ${seconds !== void 0 ? seconds + "s" : minutes}.`);
+  }
+  return resolved;
+}
 function validateLineItem(li) {
   if ("price_id" in li) return li;
   const hasHuman = li.amount != null;
   const hasAtomic = li.amount_atomic != null;
   if (hasHuman === hasAtomic) {
-    throw new Error('[BitPal] line item requires exactly one of `amount` (USD number, e.g. "29") or `amount_atomic` (raw \u03BCUSD integer, e.g. "29000000").');
+    throw new Error('[BitPal] line item requires exactly one of `amount` (canonical decimal number, e.g. "29") or `amount_atomic` (raw canonical 6dp integer, e.g. "29000000").');
   }
   return li;
 }
@@ -186,10 +200,18 @@ var BitPalCheckoutClient = class {
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
-      const json = await res.json();
+      const text = await res.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+        if (!res.ok) throw new BitPalError(`HTTP ${res.status}`, res.status);
+        throw new BitPalError(`Invalid JSON response (HTTP ${res.status})`, res.status);
+      }
       if (!res.ok) {
-        const msg = json.error ?? `HTTP ${res.status}`;
-        throw new BitPalError(String(msg), res.status);
+        const err = json && typeof json === "object" ? json.error : void 0;
+        const msg = typeof err === "string" && err.length > 0 ? err : `HTTP ${res.status}`;
+        throw new BitPalError(msg, res.status, parseApiErrorBody(json));
       }
       return json;
     } finally {
@@ -200,14 +222,16 @@ var BitPalCheckoutClient = class {
   /**
    * 체크아웃 세션 생성.
    *
-   * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
-   * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
+   * `line_items[].amount` 는 사람 표기 canonical 6dp 문자열("29", "0.5") — decimal 계산 불필요.
+   * `currency`('USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정하고, amount 는 항상 그 통화 기준 값이다
+   * (USD 로 고정된 게 아님 — currency='JPYC' + amount='1500' → 1500엔/1500 JPYC, 환율 변환 없음).
+   * 이미 raw canonical 6dp 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
    *
    * @example
    * import { BitPal } from '@bitpal/checkout';
    * const bp = new BitPal('bp_test_...');
    * const { data } = await bp.checkout.createSession({
-   *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+   *   // amount: 사람 표기 canonical 6dp("29", "0.5"). 체인/토큰 decimal 은 발급 시 서버가 재스케일.
    *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
    * });
    * console.log(data.url); // → buyer를 redirect할 결제 페이지
@@ -224,8 +248,11 @@ var BitPalCheckoutClient = class {
     if (params.pay_chain && params.allowed_pay_chains && params.allowed_pay_chains.length > 0) {
       throw new Error("[BitPal] pay_chain and allowed_pay_chains are mutually exclusive \u2014 use only one.");
     }
+    const { expires_in_seconds, payer_wallet: _payerWallet, pay_asset: _payAsset, ...rest } = params;
+    const expiresInMinutes = resolveExpiryMinutes(params.expires_in_minutes, expires_in_seconds);
     const body = {
-      ...params,
+      ...rest,
+      ...expiresInMinutes !== void 0 ? { expires_in_minutes: expiresInMinutes } : {},
       line_items: params.line_items.map(validateLineItem),
       ...params.allowed_assets ? { allowed_assets: params.allowed_assets.map((a) => ({ caip2: a.chain, token: a.token })) } : {}
     };
@@ -336,12 +363,37 @@ var BitPalCheckoutClient = class {
 };
 var BitPalError = class extends Error {
   statusCode;
-  constructor(message, statusCode) {
+  code;
+  apiMessage;
+  retryable;
+  traceId;
+  constructor(message, statusCode, details = {}) {
     super(message);
     this.name = "BitPalError";
     this.statusCode = statusCode;
+    this.code = details.code;
+    this.apiMessage = details.apiMessage;
+    this.retryable = details.retryable;
+    this.traceId = details.traceId;
   }
 };
+var ERROR_CODE_RE = /^[A-Z][A-Z0-9_]*$/;
+function parseApiErrorBody(body) {
+  if (!body || typeof body !== "object") return {};
+  const b = body;
+  const str = (v) => typeof v === "string" && v.length > 0 ? v : void 0;
+  const error = str(b.error);
+  const explicitCode = str(b.code);
+  const message = str(b.message);
+  const code = explicitCode ?? (error && ERROR_CODE_RE.test(error) ? error : void 0);
+  const apiMessage = message ?? (explicitCode && error && error !== explicitCode ? error : void 0);
+  return {
+    code,
+    apiMessage,
+    retryable: typeof b.retryable === "boolean" ? b.retryable : void 0,
+    traceId: str(b.trace_id)
+  };
+}
 
 // src/webhook.ts
 var CHECKOUT_WEBHOOK_EVENTS = [
@@ -978,6 +1030,7 @@ var BitPal = class {
   fromAtomic,
   fromAtomicUSDC,
   normalizeSignature,
+  parseApiErrorBody,
   parseWebhookEvent,
   toAtomic,
   toAtomicUSDC,

package/dist/index.d.cts

@@ -9,9 +9,11 @@ interface BitPalConfig {
      *
      * BitPal 콘솔 → Developers → API Keys 에서 발급.
      *
-     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. 그러나 buyer-facing 공개 메서드
-     * (getPublicSession/getStatus/issueDepositAddress)는 인증 불요(session_token 기반)이므로 브라우저에서
-     * apiKey 없이 쓸 수 있다 — 절대 secret 키를 브라우저에 노출하지 말 것.
+     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. buyer-facing 공개 메서드
+     * (getPublicSession/getStatus/issueDepositAddress)는 apiKey 가 필요 없다(issueDepositAddress 는 session_token 필요).
+     * 단 **브라우저(CORS)** 에서 임의 머천트 도메인이 직접 부를 수 있는 것은 `getPublicSession` 뿐이다 —
+     * `issueDepositAddress`/`getStatus` 는 머천트 백엔드를 경유해 호출한다(자체 결제 UI = 헤드리스 checkout).
+     * 절대 secret 키를 브라우저에 노출하지 말 것.
      */
     apiKey?: string;
     /**
@@ -25,28 +27,30 @@ interface BitPalConfig {
     /** 요청 타임아웃 (ms, 기본값: 30000) */
     timeout?: number;
 }
-/** 응답/정규화된 line item — amount 는 항상 atomic μUSD 정수. */
+/** 응답/정규화된 line item — amount 는 항상 canonical 6dp atomic 정수(실제 결제 토큰 decimals 아님). */
 interface LineItem {
     name: string;
-    /** Atomic μUSD 정수 문자열($1="1000000", $29="29000000"). */
+    /** canonical 6dp atomic 정수 문자열("1"="1000000", "29"="29000000"). */
     amount: string;
     currency: string;
     quantity?: number;
 }
 /**
  * 세션 생성 입력용 line item. 금액은 둘 중 **하나**:
- *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
- *     ※ 금액은 **USD 가격**이다(체인/토큰 decimal 무관). 토큰(USDC 6dp / BNB USDT 18dp)별 스케일은 발급 시 서버가 처리.
- *   - `amount_atomic`: 이미 raw μUSD 정수 문자열($1="1000000")인 경우(고급/기존 코드).
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
+ *     ※ `currency`(예: 'USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정한다 — `amount`는 그 통화의 canonical
+ *     6dp 표기일 뿐 항상 USD 를 뜻하지 않는다(예: currency='JPYC' + amount="29" → 29 JPYC/29엔, 환율
+ *     변환 없음). 실제 결제 토큰 decimals(USDC 6dp / JPYC 18dp 등)로의 재스케일은 발급 시 서버가 처리.
+ *   - `amount_atomic`: 이미 raw canonical 6dp 정수 문자열($1="1000000")인 경우(고급/기존 코드).
  * 둘 다 지정하거나 둘 다 생략하면 SDK 가 에러를 throw 한다.
  */
 interface LineItemInput {
     name: string;
     currency: string;
     quantity?: number;
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
 }
 interface PriceLineItem {
@@ -57,7 +61,7 @@ interface PriceLineItem {
 type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
     line_items: CheckoutLineItemInput[];
-    /** 고객 지갑 주소 (선택) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 입금자 주소는 결제 시 온체인에서 기록된다. */
     payer_wallet?: string;
     /** 결제 체인 (예: eip155:8453). 단일 고정 — allowed_pay_chains와 상호 배타. */
     pay_chain?: string;
@@ -78,11 +82,19 @@ interface CreateSessionParams {
         chain: string;
         token: string;
     }>;
-    /** 결제 자산 (예: USDC) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 결제 자산은 `allowed_assets` 로 지정한다. */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
     tolerance_percent?: string;
-    /** 만료 시간 (초, 기본값: 1800) */
+    /**
+     * 결제 대기 시간(분). 1~60, 기본 15. 이 시간이 지나면 세션이 만료된다
+     * (만료 후 도착한 정확 금액은 7일 안이면 늦은 결제로 인정 — `late: true`).
+     */
+    expires_in_minutes?: number;
+    /**
+     * @deprecated `expires_in_minutes` 를 쓴다. 60~3600 초만 허용되고 분 단위로 올림해 보낸다.
+     * (0.11 까지는 서버가 이 필드를 몰라 무시했고, 항상 기본 15분이 적용됐다.)
+     */
     expires_in_seconds?: number;
     /** 메타데이터 (모든 값은 string 이어야 함) */
     metadata?: Record<string, string>;
@@ -141,9 +153,18 @@ interface PublicSession {
     status: string;
     mode: string | null;
     currency: string;
-    /** Atomic 정수 문자열(토큰 decimals 기준). */
+    /**
+     * 주문 총액 — **canonical μUSD(6dp) 정수 문자열**(가격 통화 기준, $1 = "1000000"). 결제 토큰 decimals 와 무관하다
+     * (18dp 토큰으로 결제해도 6dp). 온체인으로 보낼 토큰 단위 금액은 `pay_amount`(또는 발급 응답 `expectedAmount`).
+     */
     amount_total: string;
+    /** 지금까지 입금주소에 들어온 금액 — **결제 토큰 atomic**(`token_decimals` 기준). 미입금이면 null. */
     amount_received?: string | null;
+    /**
+     * 선택된 결제 토큰 단위의 총액(atomic, `token_decimals` 기준) — 구매자가 송금할 정확 금액. 자산 미선택이면 null.
+     * = canonicalToTokenAtomic(amount_total, token_decimals). 부족액 = pay_amount − amount_received.
+     */
+    pay_amount?: string | null;
     pay_chain: string | null;
     pay_asset: string | null;
     /** 발급된 주문별 forwarder 입금주소(미발급이면 null). */
@@ -152,7 +173,7 @@ interface PublicSession {
     payment_options: PaymentOption[];
     chain_id: number | null;
     token_address: string | null;
-    /** 선택된 pay 토큰 decimals(발급 후). amount_total/amount_received atomic 해석에 사용 — 6dp 가정 금지. */
+    /** 선택된 pay 토큰 decimals(발급 후). amount_received / pay_amount 해석에 사용 — 6dp 가정 금지(amount_total 은 항상 6dp). */
     token_decimals?: number | null;
     tx_hash: string | null;
     release_tx_hash?: string | null;
@@ -284,16 +305,23 @@ interface UpdateProductParams {
 }
 /**
  * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
- *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
- *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw canonical 6dp 정수($1="1000000") — 고급/기존.
  * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ *
+ * `amount`/`amount_atomic`은 실제 결제 토큰의 decimals 가 아니라 **항상 canonical 6dp**다 — 서버가
+ * 결제 시점에 실제 토큰 decimals(예: JPYC=18dp)로 재스케일한다(1:1 가정, 환율 변환 없음). 즉
+ * `token_symbol: 'JPYC'`로 "29"를 등록하면 29 JPYC(≈29엔)로 결제되지, 29 USD 상당의 JPYC로
+ * 환산되지 않는다.
+ *
+ * `currency`는 입력받지 않는다 — 서버가 `token_symbol`에서 파생한다(불일치 방지).
  */
 interface CreatePriceParams {
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
-    currency?: string;
+    /** 'USDC' | 'USDT' | 'JPYC' — 미지정 시 'USDC'. 이 Price 의 유일한 결제 자산(currency 는 여기서 파생). */
     token_symbol?: string;
     billing_type?: 'one_time';
     nickname?: string;
@@ -492,14 +520,16 @@ declare class BitPalCheckoutClient {
     /**
      * 체크아웃 세션 생성.
      *
-     * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
-     * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
+     * `line_items[].amount` 는 사람 표기 canonical 6dp 문자열("29", "0.5") — decimal 계산 불필요.
+     * `currency`('USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정하고, amount 는 항상 그 통화 기준 값이다
+     * (USD 로 고정된 게 아님 — currency='JPYC' + amount='1500' → 1500엔/1500 JPYC, 환율 변환 없음).
+     * 이미 raw canonical 6dp 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
      *
      * @example
      * import { BitPal } from '@bitpal/checkout';
      * const bp = new BitPal('bp_test_...');
      * const { data } = await bp.checkout.createSession({
-     *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+     *   // amount: 사람 표기 canonical 6dp("29", "0.5"). 체인/토큰 decimal 은 발급 시 서버가 재스케일.
      *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      * });
      * console.log(data.url); // → buyer를 redirect할 결제 페이지
@@ -571,10 +601,32 @@ declare class BitPalCheckoutClient {
         amountAtomic: string;
     }): Promise<ApiResponse<FeePreview>>;
 }
+/** Structured fields parsed from an API error body. All optional — older endpoints omit some. */
+interface BitPalErrorDetails {
+    /** Machine-readable error code, e.g. `"FEATURE_NOT_ENABLED"`. */
+    code?: string;
+    /** Human-readable message from the API, when it sent one separately from the code. */
+    apiMessage?: string;
+    /** Whether retrying the same request may succeed. */
+    retryable?: boolean;
+    /** Server trace id — include it when contacting support. */
+    traceId?: string;
+}
 declare class BitPalError extends Error {
     readonly statusCode: number;
-    constructor(message: string, statusCode: number);
+    readonly code?: string;
+    readonly apiMessage?: string;
+    readonly retryable?: boolean;
+    readonly traceId?: string;
+    constructor(message: string, statusCode: number, details?: BitPalErrorDetails);
 }
+/**
+ * API 에러 body → BitPalError 상세. 두 가지 shape 를 모두 읽는다:
+ *   - 표준: `{ error: <message>, code, retryable, trace_id }`
+ *   - 일부 라우트: `{ error: <CODE>, message }`
+ * `message`(Error.message)는 0.11 과 같게 `body.error` 를 유지한다(하위 호환) — 추가 정보는 필드로만.
+ */
+declare function parseApiErrorBody(body: unknown): BitPalErrorDetails;
 
 /**
  * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
@@ -1124,4 +1176,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPaymentLinksParams, type ListPricesParams, type ListProductsParams, type ListResponse, PaymentLinksResource, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, normalizeSignature, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, type BitPalErrorDetails, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPaymentLinksParams, type ListPricesParams, type ListProductsParams, type ListResponse, PaymentLinksResource, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, normalizeSignature, parseApiErrorBody, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };

package/dist/index.d.ts

@@ -9,9 +9,11 @@ interface BitPalConfig {
      *
      * BitPal 콘솔 → Developers → API Keys 에서 발급.
      *
-     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. 그러나 buyer-facing 공개 메서드
-     * (getPublicSession/getStatus/issueDepositAddress)는 인증 불요(session_token 기반)이므로 브라우저에서
-     * apiKey 없이 쓸 수 있다 — 절대 secret 키를 브라우저에 노출하지 말 것.
+     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. buyer-facing 공개 메서드
+     * (getPublicSession/getStatus/issueDepositAddress)는 apiKey 가 필요 없다(issueDepositAddress 는 session_token 필요).
+     * 단 **브라우저(CORS)** 에서 임의 머천트 도메인이 직접 부를 수 있는 것은 `getPublicSession` 뿐이다 —
+     * `issueDepositAddress`/`getStatus` 는 머천트 백엔드를 경유해 호출한다(자체 결제 UI = 헤드리스 checkout).
+     * 절대 secret 키를 브라우저에 노출하지 말 것.
      */
     apiKey?: string;
     /**
@@ -25,28 +27,30 @@ interface BitPalConfig {
     /** 요청 타임아웃 (ms, 기본값: 30000) */
     timeout?: number;
 }
-/** 응답/정규화된 line item — amount 는 항상 atomic μUSD 정수. */
+/** 응답/정규화된 line item — amount 는 항상 canonical 6dp atomic 정수(실제 결제 토큰 decimals 아님). */
 interface LineItem {
     name: string;
-    /** Atomic μUSD 정수 문자열($1="1000000", $29="29000000"). */
+    /** canonical 6dp atomic 정수 문자열("1"="1000000", "29"="29000000"). */
     amount: string;
     currency: string;
     quantity?: number;
 }
 /**
  * 세션 생성 입력용 line item. 금액은 둘 중 **하나**:
- *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
- *     ※ 금액은 **USD 가격**이다(체인/토큰 decimal 무관). 토큰(USDC 6dp / BNB USDT 18dp)별 스케일은 발급 시 서버가 처리.
- *   - `amount_atomic`: 이미 raw μUSD 정수 문자열($1="1000000")인 경우(고급/기존 코드).
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5", "29.00"). decimal 신경 쓸 필요 없음.
+ *     ※ `currency`(예: 'USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정한다 — `amount`는 그 통화의 canonical
+ *     6dp 표기일 뿐 항상 USD 를 뜻하지 않는다(예: currency='JPYC' + amount="29" → 29 JPYC/29엔, 환율
+ *     변환 없음). 실제 결제 토큰 decimals(USDC 6dp / JPYC 18dp 등)로의 재스케일은 발급 시 서버가 처리.
+ *   - `amount_atomic`: 이미 raw canonical 6dp 정수 문자열($1="1000000")인 경우(고급/기존 코드).
  * 둘 다 지정하거나 둘 다 생략하면 SDK 가 에러를 throw 한다.
  */
 interface LineItemInput {
     name: string;
     currency: string;
     quantity?: number;
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
 }
 interface PriceLineItem {
@@ -57,7 +61,7 @@ interface PriceLineItem {
 type CheckoutLineItemInput = LineItemInput | PriceLineItem;
 interface CreateSessionParams {
     line_items: CheckoutLineItemInput[];
-    /** 고객 지갑 주소 (선택) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 입금자 주소는 결제 시 온체인에서 기록된다. */
     payer_wallet?: string;
     /** 결제 체인 (예: eip155:8453). 단일 고정 — allowed_pay_chains와 상호 배타. */
     pay_chain?: string;
@@ -78,11 +82,19 @@ interface CreateSessionParams {
         chain: string;
         token: string;
     }>;
-    /** 결제 자산 (예: USDC) */
+    /** @deprecated 서버가 사용하지 않는다(무시됨). 결제 자산은 `allowed_assets` 로 지정한다. */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
     tolerance_percent?: string;
-    /** 만료 시간 (초, 기본값: 1800) */
+    /**
+     * 결제 대기 시간(분). 1~60, 기본 15. 이 시간이 지나면 세션이 만료된다
+     * (만료 후 도착한 정확 금액은 7일 안이면 늦은 결제로 인정 — `late: true`).
+     */
+    expires_in_minutes?: number;
+    /**
+     * @deprecated `expires_in_minutes` 를 쓴다. 60~3600 초만 허용되고 분 단위로 올림해 보낸다.
+     * (0.11 까지는 서버가 이 필드를 몰라 무시했고, 항상 기본 15분이 적용됐다.)
+     */
     expires_in_seconds?: number;
     /** 메타데이터 (모든 값은 string 이어야 함) */
     metadata?: Record<string, string>;
@@ -141,9 +153,18 @@ interface PublicSession {
     status: string;
     mode: string | null;
     currency: string;
-    /** Atomic 정수 문자열(토큰 decimals 기준). */
+    /**
+     * 주문 총액 — **canonical μUSD(6dp) 정수 문자열**(가격 통화 기준, $1 = "1000000"). 결제 토큰 decimals 와 무관하다
+     * (18dp 토큰으로 결제해도 6dp). 온체인으로 보낼 토큰 단위 금액은 `pay_amount`(또는 발급 응답 `expectedAmount`).
+     */
     amount_total: string;
+    /** 지금까지 입금주소에 들어온 금액 — **결제 토큰 atomic**(`token_decimals` 기준). 미입금이면 null. */
     amount_received?: string | null;
+    /**
+     * 선택된 결제 토큰 단위의 총액(atomic, `token_decimals` 기준) — 구매자가 송금할 정확 금액. 자산 미선택이면 null.
+     * = canonicalToTokenAtomic(amount_total, token_decimals). 부족액 = pay_amount − amount_received.
+     */
+    pay_amount?: string | null;
     pay_chain: string | null;
     pay_asset: string | null;
     /** 발급된 주문별 forwarder 입금주소(미발급이면 null). */
@@ -152,7 +173,7 @@ interface PublicSession {
     payment_options: PaymentOption[];
     chain_id: number | null;
     token_address: string | null;
-    /** 선택된 pay 토큰 decimals(발급 후). amount_total/amount_received atomic 해석에 사용 — 6dp 가정 금지. */
+    /** 선택된 pay 토큰 decimals(발급 후). amount_received / pay_amount 해석에 사용 — 6dp 가정 금지(amount_total 은 항상 6dp). */
     token_decimals?: number | null;
     tx_hash: string | null;
     release_tx_hash?: string | null;
@@ -284,16 +305,23 @@ interface UpdateProductParams {
 }
 /**
  * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
- *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
- *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ *   - `amount`(권장): 사람 표기 canonical 6dp 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw canonical 6dp 정수($1="1000000") — 고급/기존.
  * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ *
+ * `amount`/`amount_atomic`은 실제 결제 토큰의 decimals 가 아니라 **항상 canonical 6dp**다 — 서버가
+ * 결제 시점에 실제 토큰 decimals(예: JPYC=18dp)로 재스케일한다(1:1 가정, 환율 변환 없음). 즉
+ * `token_symbol: 'JPYC'`로 "29"를 등록하면 29 JPYC(≈29엔)로 결제되지, 29 USD 상당의 JPYC로
+ * 환산되지 않는다.
+ *
+ * `currency`는 입력받지 않는다 — 서버가 `token_symbol`에서 파생한다(불일치 방지).
  */
 interface CreatePriceParams {
-    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    /** 사람 표기 canonical 6dp 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
     amount?: string;
-    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    /** raw canonical 6dp 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
     amount_atomic?: string;
-    currency?: string;
+    /** 'USDC' | 'USDT' | 'JPYC' — 미지정 시 'USDC'. 이 Price 의 유일한 결제 자산(currency 는 여기서 파생). */
     token_symbol?: string;
     billing_type?: 'one_time';
     nickname?: string;
@@ -492,14 +520,16 @@ declare class BitPalCheckoutClient {
     /**
      * 체크아웃 세션 생성.
      *
-     * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
-     * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
+     * `line_items[].amount` 는 사람 표기 canonical 6dp 문자열("29", "0.5") — decimal 계산 불필요.
+     * `currency`('USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정하고, amount 는 항상 그 통화 기준 값이다
+     * (USD 로 고정된 게 아님 — currency='JPYC' + amount='1500' → 1500엔/1500 JPYC, 환율 변환 없음).
+     * 이미 raw canonical 6dp 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
      *
      * @example
      * import { BitPal } from '@bitpal/checkout';
      * const bp = new BitPal('bp_test_...');
      * const { data } = await bp.checkout.createSession({
-     *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+     *   // amount: 사람 표기 canonical 6dp("29", "0.5"). 체인/토큰 decimal 은 발급 시 서버가 재스케일.
      *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
      * });
      * console.log(data.url); // → buyer를 redirect할 결제 페이지
@@ -571,10 +601,32 @@ declare class BitPalCheckoutClient {
         amountAtomic: string;
     }): Promise<ApiResponse<FeePreview>>;
 }
+/** Structured fields parsed from an API error body. All optional — older endpoints omit some. */
+interface BitPalErrorDetails {
+    /** Machine-readable error code, e.g. `"FEATURE_NOT_ENABLED"`. */
+    code?: string;
+    /** Human-readable message from the API, when it sent one separately from the code. */
+    apiMessage?: string;
+    /** Whether retrying the same request may succeed. */
+    retryable?: boolean;
+    /** Server trace id — include it when contacting support. */
+    traceId?: string;
+}
 declare class BitPalError extends Error {
     readonly statusCode: number;
-    constructor(message: string, statusCode: number);
+    readonly code?: string;
+    readonly apiMessage?: string;
+    readonly retryable?: boolean;
+    readonly traceId?: string;
+    constructor(message: string, statusCode: number, details?: BitPalErrorDetails);
 }
+/**
+ * API 에러 body → BitPalError 상세. 두 가지 shape 를 모두 읽는다:
+ *   - 표준: `{ error: <message>, code, retryable, trace_id }`
+ *   - 일부 라우트: `{ error: <CODE>, message }`
+ * `message`(Error.message)는 0.11 과 같게 `body.error` 를 유지한다(하위 호환) — 추가 정보는 필드로만.
+ */
+declare function parseApiErrorBody(body: unknown): BitPalErrorDetails;
 
 /**
  * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
@@ -1124,4 +1176,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPaymentLinksParams, type ListPricesParams, type ListProductsParams, type ListResponse, PaymentLinksResource, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, normalizeSignature, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, type BitPalErrorDetails, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPaymentLinksParams, type ListPricesParams, type ListProductsParams, type ListResponse, PaymentLinksResource, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, normalizeSignature, parseApiErrorBody, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };

package/dist/index.js

@@ -79,12 +79,25 @@ var PaymentLinksResource = class {
 };
 
 // src/client.ts
+var EXPIRY_MIN_MINUTES = 1;
+var EXPIRY_MAX_MINUTES = 60;
+function resolveExpiryMinutes(minutes, seconds) {
+  if (minutes !== void 0 && seconds !== void 0) {
+    throw new Error("[BitPal] pass only one of `expires_in_minutes` or `expires_in_seconds`.");
+  }
+  const resolved = seconds !== void 0 ? Math.ceil(seconds / 60) : minutes;
+  if (resolved === void 0) return void 0;
+  if (!Number.isInteger(resolved) || resolved < EXPIRY_MIN_MINUTES || resolved > EXPIRY_MAX_MINUTES) {
+    throw new Error(`[BitPal] session expiry must be ${EXPIRY_MIN_MINUTES}\u2013${EXPIRY_MAX_MINUTES} minutes (expires_in_minutes) \u2014 got ${seconds !== void 0 ? seconds + "s" : minutes}.`);
+  }
+  return resolved;
+}
 function validateLineItem(li) {
   if ("price_id" in li) return li;
   const hasHuman = li.amount != null;
   const hasAtomic = li.amount_atomic != null;
   if (hasHuman === hasAtomic) {
-    throw new Error('[BitPal] line item requires exactly one of `amount` (USD number, e.g. "29") or `amount_atomic` (raw \u03BCUSD integer, e.g. "29000000").');
+    throw new Error('[BitPal] line item requires exactly one of `amount` (canonical decimal number, e.g. "29") or `amount_atomic` (raw canonical 6dp integer, e.g. "29000000").');
   }
   return li;
 }
@@ -127,10 +140,18 @@ var BitPalCheckoutClient = class {
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
-      const json = await res.json();
+      const text = await res.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+        if (!res.ok) throw new BitPalError(`HTTP ${res.status}`, res.status);
+        throw new BitPalError(`Invalid JSON response (HTTP ${res.status})`, res.status);
+      }
       if (!res.ok) {
-        const msg = json.error ?? `HTTP ${res.status}`;
-        throw new BitPalError(String(msg), res.status);
+        const err = json && typeof json === "object" ? json.error : void 0;
+        const msg = typeof err === "string" && err.length > 0 ? err : `HTTP ${res.status}`;
+        throw new BitPalError(msg, res.status, parseApiErrorBody(json));
       }
       return json;
     } finally {
@@ -141,14 +162,16 @@ var BitPalCheckoutClient = class {
   /**
    * 체크아웃 세션 생성.
    *
-   * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
-   * 이미 raw μUSD 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
+   * `line_items[].amount` 는 사람 표기 canonical 6dp 문자열("29", "0.5") — decimal 계산 불필요.
+   * `currency`('USDC'/'USDT'/'JPYC')가 실제 결제 통화를 결정하고, amount 는 항상 그 통화 기준 값이다
+   * (USD 로 고정된 게 아님 — currency='JPYC' + amount='1500' → 1500엔/1500 JPYC, 환율 변환 없음).
+   * 이미 raw canonical 6dp 정수라면 `amount_atomic`("29000000") 사용(고급). 둘은 상호 배타.
    *
    * @example
    * import { BitPal } from '@bitpal/checkout';
    * const bp = new BitPal('bp_test_...');
    * const { data } = await bp.checkout.createSession({
-   *   // amount: 사람 표기 USD("29", "0.5"). 금액은 USD 가격이라 체인/토큰 decimal 무관.
+   *   // amount: 사람 표기 canonical 6dp("29", "0.5"). 체인/토큰 decimal 은 발급 시 서버가 재스케일.
    *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
    * });
    * console.log(data.url); // → buyer를 redirect할 결제 페이지
@@ -165,8 +188,11 @@ var BitPalCheckoutClient = class {
     if (params.pay_chain && params.allowed_pay_chains && params.allowed_pay_chains.length > 0) {
       throw new Error("[BitPal] pay_chain and allowed_pay_chains are mutually exclusive \u2014 use only one.");
     }
+    const { expires_in_seconds, payer_wallet: _payerWallet, pay_asset: _payAsset, ...rest } = params;
+    const expiresInMinutes = resolveExpiryMinutes(params.expires_in_minutes, expires_in_seconds);
     const body = {
-      ...params,
+      ...rest,
+      ...expiresInMinutes !== void 0 ? { expires_in_minutes: expiresInMinutes } : {},
       line_items: params.line_items.map(validateLineItem),
       ...params.allowed_assets ? { allowed_assets: params.allowed_assets.map((a) => ({ caip2: a.chain, token: a.token })) } : {}
     };
@@ -277,12 +303,37 @@ var BitPalCheckoutClient = class {
 };
 var BitPalError = class extends Error {
   statusCode;
-  constructor(message, statusCode) {
+  code;
+  apiMessage;
+  retryable;
+  traceId;
+  constructor(message, statusCode, details = {}) {
     super(message);
     this.name = "BitPalError";
     this.statusCode = statusCode;
+    this.code = details.code;
+    this.apiMessage = details.apiMessage;
+    this.retryable = details.retryable;
+    this.traceId = details.traceId;
   }
 };
+var ERROR_CODE_RE = /^[A-Z][A-Z0-9_]*$/;
+function parseApiErrorBody(body) {
+  if (!body || typeof body !== "object") return {};
+  const b = body;
+  const str = (v) => typeof v === "string" && v.length > 0 ? v : void 0;
+  const error = str(b.error);
+  const explicitCode = str(b.code);
+  const message = str(b.message);
+  const code = explicitCode ?? (error && ERROR_CODE_RE.test(error) ? error : void 0);
+  const apiMessage = message ?? (explicitCode && error && error !== explicitCode ? error : void 0);
+  return {
+    code,
+    apiMessage,
+    retryable: typeof b.retryable === "boolean" ? b.retryable : void 0,
+    traceId: str(b.trace_id)
+  };
+}
 
 // src/webhook.ts
 var CHECKOUT_WEBHOOK_EVENTS = [
@@ -918,6 +969,7 @@ export {
   fromAtomic,
   fromAtomicUSDC,
   normalizeSignature,
+  parseApiErrorBody,
   parseWebhookEvent,
   toAtomic,
   toAtomicUSDC,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.11.0",
+  "version": "0.12.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": {
@@ -29,7 +29,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "bitpal",
@@ -52,17 +53,16 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "lint": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "npm test && npm run build",
-    "release": "npm publish --access public"
-  },
   "devDependencies": {
-    "@types/node": "^20.11.0",
     "tsup": "^8.5.1",
     "typescript": "^5.5.0",
     "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "release": "pnpm publish --access public --no-git-checks",
+    "sync:mirror": "node scripts/sync-mirror.mjs"
   }
-}
+}