@bitpal/checkout 0.10.0 → 0.12.0

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 = [
@@ -485,11 +536,11 @@ var X402Gate = class {
     } catch {
       return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
     }
-    const merchant = payload?.payload?.merchant;
-    if (!merchant?.from || !merchant?.nonce) {
+    const auth = payload?.payload?.authorization;
+    if (!auth?.from || !auth?.nonce) {
       return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
     }
-    const key = `${payload.network}:${merchant.from.toLowerCase()}:${merchant.nonce.toLowerCase()}`;
+    const key = `${payload.network}:${auth.from.toLowerCase()}:${auth.nonce.toLowerCase()}`;
     const claim = await this.store.claim(key, this.maxTimeoutSeconds);
     if (claim === "used") {
       return {
@@ -527,7 +578,12 @@ var X402Gate = class {
       },
       paymentRequirements: {
         asset: accept.asset,
+        // payer 가 서명한 목적지 = 분배 조건을 커밋한 정산 주소.
         payTo: accept.payTo,
+        // 머천트 정산 지갑. facilitator 가 이 값으로 정산 주소를 재계산해 payTo 와 대조한다 —
+        //   CREATE2 는 단방향이라 payTo 에서 되돌릴 수 없으므로 따로 보내야 한다.
+        //   우리 설정값을 그대로 쓴다(402 응답에서 읽지 않는다 — 그러면 재계산의 의미가 없다).
+        merchant: this.opts.payTo,
         maxAmountRequired: accept.maxAmountRequired,
         resource: accept.resource
       }
@@ -579,7 +635,7 @@ var X402Gate = class {
       txHash: settled.tx_hash,
       feeTxHash: settled.fee_tx_hash ?? null,
       network: settled.network,
-      payer: merchant.from,
+      payer: auth.from,
       amount: accept.maxAmountRequired,
       idempotent: settled.idempotent ?? false
     };
@@ -591,7 +647,7 @@ var X402Gate = class {
         success: true,
         transaction: settled.tx_hash,
         network: settled.network,
-        payer: merchant.from,
+        payer: auth.from,
         paymentId: settled.payment_id
       }),
       // 소진 확정은 **응답을 실제로 내준 뒤**다. 핸들러가 throw 하거나 프로세스가 죽으면 결제만 하고
@@ -712,18 +768,22 @@ function assertPaymentPayload(value) {
     throw new Error("[BitPal] x402: invalid network.");
   }
   const inner = asObject(root.payload, "payload");
-  const merchant = assertAuthorization(inner.merchant, "merchant");
-  const fee = inner.fee === void 0 ? void 0 : assertAuthorization(inner.fee, "fee");
+  if (typeof inner.signature !== "string" || !PACKED_SIG_RE.test(inner.signature)) {
+    throw new Error("[BitPal] x402: invalid payload.signature (expected 65-byte packed hex).");
+  }
   return {
     x402Version: 1,
     scheme: "exact",
     network: root.network,
-    payload: fee ? { merchant, fee } : { merchant }
+    payload: {
+      signature: inner.signature,
+      authorization: assertAuthorization(inner.authorization, "authorization")
+    }
   };
 }
+var PACKED_SIG_RE = /^0x[0-9a-fA-F]{130}$/;
 function assertAuthorization(value, label) {
-  const a = asObject(value, `${label} authorization`);
-  const sig = asObject(a.signature, `${label} signature`);
+  const a = asObject(value, label);
   const check = (ok, field) => {
     if (!ok) throw new Error(`[BitPal] x402: invalid ${label}.${field}.`);
   };
@@ -733,17 +793,13 @@ function assertAuthorization(value, label) {
   check(typeof a.validAfter === "string" && DECIMAL_RE.test(a.validAfter), "validAfter");
   check(typeof a.validBefore === "string" && DECIMAL_RE.test(a.validBefore), "validBefore");
   check(typeof a.nonce === "string" && HEX32_RE.test(a.nonce), "nonce");
-  check(typeof sig.v === "number" && Number.isInteger(sig.v), "signature.v");
-  check(typeof sig.r === "string" && HEX32_RE.test(sig.r), "signature.r");
-  check(typeof sig.s === "string" && HEX32_RE.test(sig.s), "signature.s");
   return {
     from: a.from,
     to: a.to,
     value: a.value,
     validAfter: a.validAfter,
     validBefore: a.validBefore,
-    nonce: a.nonce,
-    signature: { v: sig.v, r: sig.r, s: sig.s }
+    nonce: a.nonce
   };
 }
 function asObject(value, label) {
@@ -817,49 +873,33 @@ async function createX402Payment(options) {
   }
   const validAfter = "0";
   const validBefore = String(now + validFor);
-  const nextNonce = options.randomNonce ?? randomNonce;
-  const fee = accept.feeBreakdown;
-  const feeAmount = fee ? BigInt(fee.feeAmount) : 0n;
-  const merchantValue = fee ? fee.netAmount : accept.maxAmountRequired;
-  const merchant = await signAuthorization({
-    domain,
-    signTypedData: options.signTypedData,
+  const nonce = (options.randomNonce ?? randomNonce)();
+  const authorization = {
     from: options.from,
     to: accept.payTo,
-    value: merchantValue,
+    value: accept.maxAmountRequired,
     validAfter,
     validBefore,
-    nonce: nextNonce()
-  });
-  let feeLeg;
-  if (feeAmount > 0n) {
-    if (!fee?.feeRecipient) {
-      throw new Error("[BitPal] x402: feeAmount > 0 but feeRecipient is missing in the 402 response.");
-    }
-    feeLeg = await signAuthorization({
+    nonce
+  };
+  const signature = normalizeSignature(
+    await options.signTypedData({
       domain,
-      signTypedData: options.signTypedData,
-      from: options.from,
-      to: fee.feeRecipient,
-      value: fee.feeAmount,
-      validAfter,
-      validBefore,
-      nonce: nextNonce()
-    });
-    if (feeLeg.nonce.toLowerCase() === merchant.nonce.toLowerCase()) {
-      throw new Error("[BitPal] x402: the two authorizations must use different nonces.");
-    }
-  }
+      types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+      primaryType: "TransferWithAuthorization",
+      message: authorization
+    })
+  );
   const payload = {
     x402Version: 1,
     scheme: "exact",
     network: accept.network,
-    payload: feeLeg ? { merchant, fee: feeLeg } : { merchant }
+    payload: { signature, authorization }
   };
   return {
     header: encodePaymentHeader(payload),
     payload,
-    totalAmount: (BigInt(merchantValue) + feeAmount).toString()
+    totalAmount: accept.maxAmountRequired
   };
 }
 function resolveAccept(input) {
@@ -870,41 +910,24 @@ function resolveAccept(input) {
   }
   return input;
 }
-async function signAuthorization(args) {
-  const message = {
-    from: args.from,
-    to: args.to,
-    value: args.value,
-    validAfter: args.validAfter,
-    validBefore: args.validBefore,
-    nonce: args.nonce
-  };
-  const signature = await args.signTypedData({
-    domain: args.domain,
-    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
-    primaryType: "TransferWithAuthorization",
-    message
-  });
-  return { ...message, signature: splitSignature(signature) };
-}
-function splitSignature(signature) {
+function normalizeSignature(signature) {
   const hex = signature.startsWith("0x") ? signature.slice(2) : signature;
   if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== 130 && hex.length !== 128) {
     throw new Error(
       `[BitPal] x402: expected a 65-byte or 64-byte (EIP-2098) hex signature, got ${signature.length} chars.`
     );
   }
-  const r = `0x${hex.slice(0, 64)}`;
+  const r = hex.slice(0, 64);
   if (hex.length === 128) {
     const yParityAndS = BigInt(`0x${hex.slice(64, 128)}`);
     const yParity = Number(yParityAndS >> 255n & 1n);
-    const s2 = yParityAndS & (1n << 255n) - 1n;
-    return { v: 27 + yParity, r, s: `0x${s2.toString(16).padStart(64, "0")}` };
+    const s2 = (yParityAndS & (1n << 255n) - 1n).toString(16).padStart(64, "0");
+    return `0x${r}${s2}${(27 + yParity).toString(16).padStart(2, "0")}`;
   }
-  const s = `0x${hex.slice(64, 128)}`;
+  const s = hex.slice(64, 128);
   const raw = parseInt(hex.slice(128, 130), 16);
-  if (raw === 27 || raw === 28) return { v: raw, r, s };
-  if (raw === 0 || raw === 1) return { v: raw + 27, r, s };
+  if (raw === 27 || raw === 28) return `0x${r}${s}${raw.toString(16)}`;
+  if (raw === 0 || raw === 1) return `0x${r}${s}${(raw + 27).toString(16)}`;
   throw new Error(`[BitPal] x402: unexpected signature v=${raw} (expected 0, 1, 27 or 28).`);
 }
 function randomNonce() {
@@ -945,8 +968,9 @@ export {
   encodePaymentHeader,
   fromAtomic,
   fromAtomicUSDC,
+  normalizeSignature,
+  parseApiErrorBody,
   parseWebhookEvent,
-  splitSignature,
   toAtomic,
   toAtomicUSDC,
   verifyWebhookSignature,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpal/checkout",
-  "version": "0.10.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"
   }
-}
+}