@bitpal/checkout 0.1.0

package/README.md

@@ -0,0 +1,392 @@
+# @bitpal/checkout
+
+BitPal Checkout SDK — 크립토 결제 세션 생성, 외부 on-chain 결제 검증, gasless 결제, 환불, 수수료 미리보기를 위한 공식 TypeScript SDK.
+
+## 설치
+
+```bash
+pnpm add @bitpal/checkout
+```
+
+## ⚠️ 금액 형식 (꼭 읽어주세요)
+
+BitPal API는 모든 amount를 **atomic μUSDC 정수 문자열**로 받습니다 (USDC/USDT 6 decimals).
+
+| 의미 | 보내는 값 |
+|------|-----------|
+| $1.00 | `"1000000"` |
+| $10.00 | `"10000000"` |
+| $29.00 | `"29000000"` |
+| $0.50 | `"500000"` |
+
+`"29.00"`처럼 decimal 표기로 보내면 400 에러가 떨어집니다. SDK가 제공하는 `toAtomicUSDC()` 헬퍼를 쓰세요:
+
+```ts
+import { toAtomicUSDC, fromAtomicUSDC } from '@bitpal/checkout';
+
+toAtomicUSDC('29.00');   // → '29000000'
+toAtomicUSDC('0.5');     // → '500000'
+fromAtomicUSDC('1500000'); // → '1.50'
+```
+
+이 정책은 부동소수 정밀도 손실 방지 때문이며, 모든 BitPal 라우트에 일관 적용됩니다.
+
+---
+
+## 환경 (Environments)
+
+BitPal Checkout 은 두 개의 직교 (orthogonal) 축으로 환경이 결정됩니다.
+
+| 축 | 값 | 결정 방식 | 영향 |
+|----|----|---------|------|
+| **mode** | `TEST` / `LIVE` | API 키 prefix (`bp_test_*` / `bp_live_*`) | 어떤 컨트랙트 / 정산 / webhook environment 가 사용될지 |
+| **API host** | production / local | `BitPal({ baseUrl })` | 어떤 BitPal 백엔드를 호출할지 (실서비스 vs 본인 dev 머신) |
+
+조합 매트릭스:
+
+| 시나리오 | `baseUrl` | API 키 | 실제 체인 |
+|---------|-----------|--------|----------|
+| Local 개발 (anvil) | `http://localhost:3100` | `bp_test_*` | 로컬 Hardhat/Anvil 체인 (`http://127.0.0.1:8545`) |
+| Testnet 통합 | `https://api.bitpal.io` | `bp_test_*` | Base Sepolia 등 퍼블릭 testnet |
+| Production | `https://api.bitpal.io` | `bp_live_*` | Base Mainnet |
+
+```ts
+import { BitPal } from '@bitpal/checkout';
+
+// 1) Production / testnet (BitPal 호스티드 백엔드)
+const bitpal = new BitPal({
+  apiKey: process.env.BITPAL_API_KEY!, // bp_test_* (testnet) 또는 bp_live_* (mainnet)
+});
+
+// 2) Local 개발 (본인 머신의 BitPal API + anvil)
+const bitpalLocal = new BitPal({
+  apiKey: process.env.BITPAL_API_KEY!, // bp_test_* 필수
+  baseUrl: 'http://localhost:3100',
+});
+```
+
+> 어떤 체인이든 SDK 호출 시점에 `chain: 'base'` (또는 다른 지원 체인) 만 지정하면 됩니다. mode 가 mainnet/testnet/local 컨트랙트 주소 매핑을 결정하므로 클라이언트는 체인 _이름_ 만 알면 충분합니다.
+
+## 사용법
+
+### 기본 설정
+
+```ts
+import { BitPal } from '@bitpal/checkout';
+
+// API 키는 BitPal 콘솔 → Developers → API Keys 에서 발급
+const bitpal = new BitPal({ apiKey: process.env.BITPAL_API_KEY! });
+```
+
+### 체크아웃 세션 생성
+
+```ts
+import { BitPal, toAtomicUSDC } from '@bitpal/checkout';
+
+const bitpal = new BitPal({ apiKey: process.env.BITPAL_API_KEY! });
+
+const { data: session } = await bitpal.checkout.createSession({
+  line_items: [
+    { name: 'Pro Plan', amount: toAtomicUSDC('29.00'), currency: 'USDC' },
+  ],
+  pay_chain: 'eip155:8453', // Base
+  expires_in_seconds: 1800,
+  success_url: 'https://yoursite.com/order-complete',
+  cancel_url: 'https://yoursite.com/cart',
+});
+
+// buyer를 이 URL로 redirect → BitPal이 호스팅하는 결제 페이지
+console.log(session.url);
+```
+
+### 환불 (auto — 에스크로 보관 중)
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { BitPal, toAtomicUSDC } from '@bitpal/checkout';
+
+const bitpal = new BitPal(process.env.BITPAL_API_KEY!);
+
+// 전액 환불 — amount 미지정
+const { data: full } = await bitpal.checkout.refundSession(
+  sessionId,
+  { reason: 'customer_requested' },
+  { idempotencyKey: randomUUID() },   // 동일 키 재시도 시 같은 결과 반환
+);
+console.log(full.refunded, full.txHash);  // true, '0x...' (또는 sim_xxx)
+
+// 부분 환불 — amount 명시
+const { data: partial } = await bitpal.checkout.refundSession(
+  sessionId,
+  { amount: toAtomicUSDC('5.00'), reason: 'partial_damage' },
+  { idempotencyKey: randomUUID() },
+);
+console.log(partial.type);  // 'partial'
+```
+
+머천트가 `frozen` 상태면 환불은 허용되지만, `suspended` 상태에서는 차단된다 (`merchant-status-guard`).
+
+### 환불 기록 (record — settled 후 manual offchain)
+
+```ts
+// 정산이 끝난 세션은 escrow에 자금이 없음 → 머천트가 외부 지갑에서 직접 송금하고
+// tx_hash를 입력해 환불을 DB-only로 기록한다.
+await bitpal.checkout.recordRefund(
+  sessionId,
+  {
+    refund_amount: toAtomicUSDC('5.00'),
+    tx_hash: '0x...실제 송금 tx hash',
+    reason: 'manual_offchain_refund',
+  },
+  { idempotencyKey: randomUUID() },
+);
+```
+
+### 환불 내역 조회
+
+```ts
+const { data: refunds } = await bitpal.checkout.listRefunds(sessionId);
+// auto + record 통합 list, 시간 역순
+```
+
+### 수수료 미리보기
+
+```ts
+// $100 결제의 수수료 계산
+const { data: fee } = await bitpal.checkout.previewFee(toAtomicUSDC('100'));
+// fee.fee_amount === "1500000"  (1.5% = $1.50)
+// fee.net_amount === "98500000" (= $98.50)
+
+console.log(`수수료: $${fromAtomicUSDC(fee.fee_amount)}`);
+```
+
+### Gasless external checkout payment
+
+Use `payWithAuthorization()` when your merchant UI collects an EIP-3009 USDC authorization from the buyer and wants BitPal to submit the escrow deposit with the platform relayer.
+
+```ts
+const { data: session } = await bitpal.checkout.getSession(sessionId);
+const cfg = session.external_payment_config;
+
+// Sign EIP-3009 typed data in your wallet flow using cfg.token_address,
+// cfg.escrow_contract_address, cfg.amount, and cfg.payment_id.
+const authorization = {
+  from: '0xBuyer',
+  validAfter: '0',
+  validBefore: '1778650000',
+  authNonce: '0x...',
+  v: 27,
+  r: '0x...',
+  s: '0x...',
+};
+
+const { data: payment } = await bitpal.checkout.payWithAuthorization(sessionId, {
+  chain: cfg?.chain ?? 'base',
+  session_token: session.session_token!,
+  authorization,
+});
+
+console.log(payment.status, payment.tx_hash);
+```
+
+`payWithAuthorization()` calls `POST /v1/checkout/sessions/:id/submit-payment`. The buyer signs only the authorization; BitPal's relayer submits `CheckoutEscrow.depositWithAuthorization()` and pays gas.
+
+SDK 의 반환값(`status`, `tx_hash`) 만으로 merchant 백엔드가 주문을 finalize 할 수 있습니다. webhook 등록은 **선택** — SDK 호출 없이 자동 알림이 필요한 머천트 백엔드 (비동기 잡, 다른 마이크로서비스 fan-out 등) 만 등록하면 됩니다.
+
+### External on-chain payment verification (submitExternalPayment)
+
+When the buyer deposits into `CheckoutEscrow` from their own wallet, merchant UI, or your own backend — outside the BitPal hosted page and outside `payWithAuthorization()` — submit the resulting `tx_hash` to BitPal for verification.
+
+```ts
+const { data: result } = await bitpal.checkout.submitExternalPayment(sessionId, {
+  tx_hash: '0xb81f1eb2cc8a4b32a233865c595166df563f8f009e319048f8d079abd0f3953d',
+  chain: 'base',
+});
+
+// result.validation_status: 'valid' | 'invalid' | 'underpaid' | 'overpaid' | 'duplicate'
+// result.session_status:    'paid' | 'unresolved_underpaid' | 'unresolved_overpaid' | ...
+// result.observation_id:    uuid of the checkout_payment_observations row
+// result.from_address:      payer wallet (derived from PaymentDeposited event)
+// result.amount:            atomic μUSDC received (derived from event)
+```
+
+Behaviour:
+
+- BitPal fetches the receipt, parses `CheckoutEscrow.PaymentDeposited`, and verifies `paymentId == toBytes32(sessionId)`, merchant wallet, USDC token, and amount tolerance.
+- The same `(chain_id, tx_hash, log_index)` is rejected with `validation_status: 'duplicate'` if it has already been submitted for a different session.
+- Re-submitting the same `tx_hash` for the same session is idempotent — you get the same observation row back.
+- If you're using the Ponder Mode B indexer (`apps/indexer`) the indexer calls this endpoint automatically when it sees a `PaymentDeposited` event, so you do not need to submit manually.
+
+```ts
+// Read the on-chain verification history for a session
+const { data: observations } = await bitpal.checkout.getExternalPaymentStatus(sessionId);
+const latest = observations[0];
+if (latest?.finality_status === 'final_confirmed') {
+  // 12 confirmations reached — safe to fulfil orders that require finality
+}
+```
+
+`getExternalPaymentStatus()` is the authenticated read counterpart for tenant-scoped clients. It returns the same `payment_observations` array that the merchant console session detail page shows under "On-chain Verification".
+
+#### Choosing between SDK payment methods
+
+| Method | Buyer signs | Who calls `CheckoutEscrow.deposit*` | Use when |
+|--------|------------|--------------------------------------|----------|
+| Hosted checkout (`createSession` → redirect to `session.url`) | EIP-3009 inside BitPal page | BitPal relayer | You want the simplest integration and don't need a buyer UI |
+| `payWithAuthorization()` | EIP-3009 inside your UI | BitPal relayer | Buyer stays in merchant UI, gasless for buyer |
+| `submitExternalPayment()` | Buyer signs the deposit tx in their wallet | Buyer wallet or your backend | Buyer pays their own gas, or you have a non-BitPal flow that emits `PaymentDeposited` |
+
+All three paths land in the same `CheckoutEscrow.PaymentDeposited` event and trigger the same set of webhooks (`checkout.session.paid`, `checkout.session.unresolved`, `checkout.payment.finalized`, `checkout.payment.revoked`).
+
+### 웹훅 검증
+
+```ts
+import express from 'express';
+import { verifyWebhookSignature, parseWebhookEvent, WEBHOOK_HEADERS } from '@bitpal/checkout';
+
+const app = express();
+
+// raw body 필수 — express.json() 쓰지 말 것
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  const signature = req.header(WEBHOOK_HEADERS.signature) ?? '';   // 'X-Webhook-Signature-256'
+  const isValid = await verifyWebhookSignature(
+    req.body.toString(),
+    signature,
+    process.env.BITPAL_WEBHOOK_SECRET!,
+  );
+  if (!isValid) return res.status(400).send('invalid signature');
+
+  const event = parseWebhookEvent(req.body.toString());
+  switch (event.event) {
+    case 'checkout.session.paid':
+      // DB에 주문 완료 처리 (idempotent — at-least-once 전달)
+      break;
+    case 'checkout.payment.failed':
+      // 실패 처리
+      break;
+  }
+  res.status(200).send('ok');
+});
+```
+
+#### Webhook 헤더 (canonical)
+
+BitPal backend가 모든 webhook delivery에 보내는 표준 헤더:
+
+| 헤더 | 값 | 용도 |
+|------|----|------|
+| `X-Webhook-Signature-256` | `sha256=<hex>` | HMAC-SHA256 서명 (raw body 기준) |
+| `X-Webhook-Timestamp` | ISO 시각 | envelope.created_at과 동일 |
+| `X-Webhook-Event` | `checkout.session.paid` 등 | canonical event name |
+| `X-Webhook-Id` | `evt_...` | event_id (replay 시 보존) |
+| `X-Webhook-Delivery-Id` | `dlv_...` | delivery row id |
+
+`WEBHOOK_HEADERS` 상수로 SDK에서 import 가능 — 헤더 이름 drift 방지.
+
+### ⚠️ At-least-once delivery — 머천트 idempotency 책임
+
+BitPal webhook은 **at-least-once delivery**다. 같은 이벤트가 재시도/replay/race로 인해 두 번 이상 도달할 수 있으며, 머천트 측에서 반드시 idempotent하게 처리해야 한다.
+
+**필수 패턴**:
+1. signature 검증 후
+2. `X-Webhook-Id` (또는 `X-Webhook-Delivery-Id`) 기준으로 dedup
+3. 이미 처리한 event는 200 OK만 반환하고 부작용 없이 종료
+
+```ts
+import { verifyWebhookSignature, parseWebhookEvent, WEBHOOK_HEADERS } from '@bitpal/checkout';
+
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  // 1. signature 검증
+  const sig = req.header(WEBHOOK_HEADERS.signature) ?? '';
+  const ok = await verifyWebhookSignature(req.body.toString(), sig, SECRET);
+  if (!ok) return res.status(400).send('invalid signature');
+
+  // 2. dedup — X-Webhook-Id 기준
+  const eventId = req.header(WEBHOOK_HEADERS.eventId);
+  const seen = await db.webhook_events.findUnique({ where: { event_id: eventId } });
+  if (seen) return res.status(200).send('already processed');
+
+  // 3. event 처리 + 처리 기록을 동일 트랜잭션에서
+  const event = parseWebhookEvent(req.body.toString());
+  await db.$transaction(async (tx) => {
+    await applyEvent(tx, event);                 // 비즈니스 로직
+    await tx.webhook_events.create({ data: { event_id: eventId } });  // dedup 키 기록
+  });
+
+  res.status(200).send('ok');
+});
+```
+
+dedup 키로 `X-Webhook-Id` (event 단위) 또는 `X-Webhook-Delivery-Id` (delivery 단위) 둘 다 가능 — 이벤트 단위 dedup이 일반적으로 더 안전하다 (replay도 같은 event_id 보존).
+
+---
+
+## 설정 옵션
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `apiKey` | `string` | (필수) | API 키 (`bp_test_...` 또는 `bp_live_...`) |
+| `baseUrl` | `string` | `https://api.bitpal.io` | API 기본 URL (로컬: `http://localhost:3100`) |
+| `timeout` | `number` | `30000` | 요청 타임아웃 (ms) |
+
+## 웹훅 이벤트
+
+SDK `CHECKOUT_WEBHOOK_EVENTS` 상수와 1:1 정합. 새 이벤트 추가 시 backend와 동시 갱신.
+
+| 이벤트 | 설명 |
+|--------|------|
+| `checkout.session.created` | 세션 생성됨 |
+| `checkout.session.paid` | 결제 완료 (에스크로 락) |
+| `checkout.session.settled` | 정산 완료 (에스크로 해제) |
+| `checkout.session.expired` | 세션 만료 |
+| `checkout.session.unresolved` | 세션 미해결 (수동 정정 필요) |
+| `checkout.session.release_deferred` | 머천트 frozen/suspended로 release 보류 |
+| `checkout.payment.failed` | 결제 실패 |
+| `checkout.payment.finalized` | 외부 온체인 결제 최종 확인 |
+| `checkout.payment.revoked` | 외부 온체인 결제 reorg 취소 |
+| `checkout.refund.recorded` | 환불 기록 (settled 후 manual) |
+| `checkout.refund.completed` | 환불 완료 (전액) |
+| `checkout.refund.partial` | 부분 환불 |
+
+## 통합 흐름
+
+```
+머천트 백엔드                BitPal API           Buyer
+     │                            │                  │
+     │ 1. createSession()          │                  │
+     │ ──────────────────────────► │                  │
+     │ 2. { url } 응답              │                  │
+     │ ◄──────────────────────────┤                  │
+     │                            │                  │
+     │ 3. buyer를 url로 redirect ───────────────────► │
+     │                            │                  │
+     │                            │ 4. 결제 진행      │
+     │                            │ ◄────────────────┤
+     │                            │                  │
+     │ 5. POST /merchant/webhook   │                  │
+     │ ◄─── checkout.session.paid ─┤                  │
+     │ 6. signature 검증            │                  │
+     │ 7. DB에 주문 완료 처리       │                  │
+```
+
+## 실행 가능한 예제
+
+`examples/` 디렉토리에 통합 데모가 들어있습니다:
+
+- `examples/create-session.mjs` — 세션 생성 → 결제 URL 출력
+- `examples/webhook-receiver.mjs` — webhook 수신 + 서명 검증
+
+```bash
+cd examples
+node create-session.mjs
+```
+
+## 빌드
+
+```bash
+pnpm --filter @bitpal/checkout build
+```
+
+## 라이선스
+
+Private

package/dist/index.d.ts

@@ -0,0 +1,515 @@
+/**
+ * @bitpal/checkout SDK — 타입 정의
+ */
+interface BitPalConfig {
+    /**
+     * API 키. prefix 가 mode 를 결정합니다:
+     *   - `bp_test_...` → TEST mode (testnet 또는 local anvil)
+     *   - `bp_live_...` → LIVE mode (mainnet)
+     *
+     * BitPal 콘솔 → Developers → API Keys 에서 발급.
+     */
+    apiKey: string;
+    /**
+     * BitPal API 기본 URL. 환경별로 다릅니다:
+     *   - production: `https://api.bitpal.io` (기본값) — 실제 testnet/mainnet 컨트랙트
+     *   - local dev:  `http://localhost:3100`  — anvil 로컬 체인 + 로컬 BitPal API
+     *
+     * mode (TEST/LIVE) 와 baseUrl 은 직교 (orthogonal): 어떤 baseUrl 이든 키 prefix 가 mode 를 결정.
+     */
+    baseUrl?: string;
+    /** 요청 타임아웃 (ms, 기본값: 30000) */
+    timeout?: number;
+}
+interface LineItem {
+    name: string;
+    /**
+     * Atomic μUSDC 정수 문자열 (USDC/USDT 6 decimals).
+     * $1 = "1000000", $29 = "29000000".
+     * decimal 표기는 거부된다 — `toAtomicUSDC('29.00')` 헬퍼 사용 권장.
+     */
+    amount: string;
+    currency: string;
+    quantity?: number;
+}
+interface CreateSessionParams {
+    line_items: LineItem[];
+    /** 고객 지갑 주소 (선택) */
+    payer_wallet?: string;
+    /** 결제 체인 (예: eip155:8453) */
+    pay_chain?: string;
+    /** 결제 자산 (예: USDC) */
+    pay_asset?: string;
+    /** 허용 오차 (%, 기본값: 2.00) */
+    tolerance_percent?: string;
+    /** 만료 시간 (초, 기본값: 1800) */
+    expires_in_seconds?: number;
+    /** 메타데이터 (모든 값은 string 이어야 함) */
+    metadata?: Record<string, string>;
+    /** 결제 완료 후 buyer 가 redirect 될 URL (선택) */
+    success_url?: string;
+    /** 결제 취소 시 buyer 가 redirect 될 URL (선택) */
+    cancel_url?: string;
+}
+interface CheckoutSession {
+    id: string;
+    status: string;
+    amount_total: string;
+    currency: string;
+    line_items: LineItem[];
+    pay_chain: string | null;
+    pay_asset: string | null;
+    payer_wallet: string | null;
+    seller_wallet: string;
+    tolerance_percent: string;
+    expires_at: string | null;
+    paid_at: string | null;
+    settled_at: string | null;
+    tx_hash: string | null;
+    created_at: string;
+    /** 'hosted' | 'external' — 결제 경로 구분 */
+    payment_source?: string;
+    /** External on-chain 결제 검증 기록 목록 */
+    payment_observations?: PaymentObservation[];
+    /** External/gasless checkout payment config supplied by BitPal API. */
+    external_payment_config?: ExternalPaymentConfig;
+    /** 호스티드 결제 페이지 URL (token 쿼리 포함). backend 응답 그대로 사용 — buyer를 이 URL로 redirect. */
+    checkout_url?: string;
+    /** 1회용 session token. `checkout_url`에 이미 query로 박혀 있어 별도 사용 불필요. */
+    session_token?: string;
+    /** `checkout_url`의 별칭 (backwards compat). buyer redirect 시 이 필드 또는 `checkout_url` 사용. */
+    url: string;
+}
+interface ExternalPaymentConfig {
+    chain: string;
+    chain_id: string;
+    payment_id: string;
+    escrow_contract_address: string | null;
+    token_address: string | null;
+    merchant_wallet: string;
+    amount: string;
+    fee_amount: string;
+    reserve_amount: string;
+    asset: string;
+    decimals: number;
+    supported_methods: Array<'authorization_relay'>;
+}
+/**
+ * CheckoutEscrow.PaymentDeposited 이벤트 단위 검증 기록.
+ * `GET /v1/checkout/sessions/:id` 응답의 `payment_observations` 배열 원소.
+ */
+interface PaymentObservation {
+    id: string;
+    tx_hash: string;
+    chain_id: string;
+    from_address: string | null;
+    to_address: string;
+    /** Atomic μUSDC 정수 문자열 */
+    amount: string;
+    /** 'pending' | 'valid' | 'invalid' | 'duplicate' | 'underpaid' | 'overpaid' */
+    validation_status: string;
+    /** 'detected' | 'soft_confirmed' | 'final_confirmed' | 'reorg_revoked' */
+    finality_status: string;
+    validation_error: string | null;
+    block_number: number | null;
+    confirmations: number;
+    created_at: string;
+}
+/**
+ * `submitExternalPayment` 요청 파라미터.
+ * 검증에 필요한 값은 tx_hash + chain만으로 충분 — payer_wallet, asset 등은 on-chain 이벤트에서 도출.
+ */
+interface SubmitExternalPaymentParams {
+    /** CheckoutEscrow 입금 tx hash (0x...) */
+    tx_hash: string;
+    /** 체인 식별자 (기본값: 'base'). 예: 'base', 'bnb', 'polygon' */
+    chain?: string;
+    /** Public session token — buyer 측 제출 시 사용. API key 인증 시 불필요. */
+    session_token?: string;
+}
+/**
+ * `submitExternalPayment` 응답.
+ */
+interface SubmitExternalPaymentResult {
+    observation_id: string;
+    /** 'valid' | 'invalid' | 'underpaid' | 'overpaid' | 'duplicate' */
+    validation_status: string;
+    /** 검증 후 세션 상태 */
+    session_status: string;
+    /** 입금한 지갑 주소 (on-chain 이벤트에서 도출) */
+    from_address: string | null;
+    /** Atomic μUSDC 정수 문자열 */
+    amount: string;
+    message: string;
+}
+interface PayWithAuthorizationParams {
+    chain?: string;
+    session_token: string;
+    authorization: {
+        from: string;
+        validAfter?: string;
+        validBefore: string;
+        authNonce: string;
+        v: number;
+        r: string;
+        s: string;
+    };
+}
+interface CheckoutPaymentResult {
+    status: string;
+    tx_hash: string;
+    message?: string;
+}
+/**
+ * 수수료 미리보기 응답.
+ * amount, fee_amount, net_amount는 모두 atomic μUSDC 문자열 (e.g. "1500000" = $1.50).
+ * fee_rate는 비율 문자열 (e.g. "0.015" = 1.5%).
+ */
+interface FeePreview {
+    amount: string;
+    fee_rate: string;
+    fee_amount: string;
+    net_amount: string;
+}
+/**
+ * Auto refund 파라미터 — escrow 보관 중(`escrow_status` pending|disputed)일 때 동작.
+ * 컨트랙트가 buyer에게 직접 토큰 transfer.
+ *
+ * `amount` 미지정 시 backend가 잔액 전액(full refund)을 시도. 명시 시 atomic μUSDC.
+ */
+interface RefundSessionParams {
+    /** Atomic μUSDC 정수 문자열. 미지정 시 전액. */
+    amount?: string;
+    /** 환불 사유 코드 (선택, 머천트 대시보드/audit log 분류용) */
+    reason?: string;
+    /** 환불 사유 상세 (선택, 자유 텍스트) */
+    reason_detail?: string;
+}
+interface RefundSessionResult {
+    refunded: boolean;
+    refundId: string;
+    /** Atomic μUSDC 정수 문자열 */
+    amount: string;
+    type: 'full' | 'partial';
+    /** on-chain transaction hash. simulation/escrow 미배포 환경에서는 sim_xxx */
+    txHash: string | null;
+}
+/**
+ * Record refund 파라미터 — `status='settled'` 후 머천트가 외부 지갑에서 직접 송금하고
+ * tx_hash를 입력해 환불을 DB-only로 기록한다. 컨트랙트 호출 없음.
+ */
+interface RecordRefundParams {
+    /** Atomic μUSDC 정수 문자열 (필수) */
+    refund_amount: string;
+    /** 외부 송금 transaction hash (필수, 형식 검증 안 함) */
+    tx_hash: string;
+    /** 환불 사유 (선택) */
+    reason?: string;
+}
+/**
+ * 멱등성 키 — 동일 키로 재시도 시 backend가 같은 결과 반환.
+ * Phase 1 SDK는 사용자가 명시적으로 전달 (UUID 권장).
+ */
+interface IdempotencyOptions {
+    idempotencyKey?: string;
+}
+/**
+ * `GET /v1/checkout/sessions/:id/refunds` 응답 row.
+ * 필드는 backend `listSessionRefunds` 반환과 동일 — Phase 1에서는 통합 타입 미고정 (스냅샷 시점에 따라 컬럼 변동).
+ */
+interface RefundEntry {
+    id: string;
+    session_id: string;
+    /** 'auto' | 'record' (escrow refund vs DB-only manual) */
+    refund_mode?: string;
+    amount: string;
+    /** 'pending' | 'completed' | 'failed' 등 */
+    status?: string;
+    tx_hash: string | null;
+    reason?: string | null;
+    reason_detail?: string | null;
+    created_at: string;
+    [key: string]: unknown;
+}
+interface ApiResponse<T> {
+    data: T;
+    error?: string;
+}
+interface ListResponse<T> {
+    data: T[];
+    total?: number;
+}
+
+/**
+ * @bitpal/checkout SDK — 클라이언트
+ *
+ * Phase 1 범위: 세션 생성/조회, 결제 링크 생성/조회, 수수료 미리보기.
+ * 크레딧 잔액/충전은 BitPal non-custodial 모델에서 제거됨.
+ */
+
+declare class BitPalCheckoutClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: BitPalConfig);
+    private request;
+    /**
+     * 체크아웃 세션 생성.
+     *
+     * 모든 `line_items[].amount`는 atomic μUSDC 정수 문자열이어야 한다 ($1 = "1000000").
+     * decimal 표기는 거부된다 — `toAtomicUSDC()` 헬퍼 사용 권장.
+     *
+     * @example
+     * import { BitPal, toAtomicUSDC } from '@bitpal/checkout';
+     * const bp = new BitPal('bp_test_...');
+     * const { data } = await bp.checkout.createSession({
+     *   line_items: [{ name: 'Pro', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
+     * });
+     * console.log(data.url); // → buyer를 redirect할 결제 페이지
+     */
+    createSession(params: CreateSessionParams): Promise<ApiResponse<CheckoutSession>>;
+    /** 세션 조회 */
+    getSession(sessionId: string): Promise<ApiResponse<CheckoutSession>>;
+    /** 세션 목록 조회 */
+    listSessions(params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListResponse<CheckoutSession>>;
+    /**
+     * Auto refund — escrow 보관 중일 때 컨트랙트가 buyer에게 직접 transfer.
+     *
+     * `params.amount` 미지정 시 backend가 잔액 전액(`type: 'full'`). 명시 시 `type: 'partial'`.
+     * **Idempotency-Key 권장** — 같은 키로 재시도 시 backend가 같은 결과 반환.
+     *
+     * 머천트가 `frozen` 상태면 환불은 허용되지만, `suspended` 상태에서는 차단된다.
+     *
+     * @example
+     * ```ts
+     * import { randomUUID } from 'node:crypto';
+     * const { data } = await bitpal.checkout.refundSession(
+     *   sessionId,
+     *   { amount: toAtomicUSDC('5.00'), reason: 'customer_requested' },
+     *   { idempotencyKey: randomUUID() },
+     * );
+     * console.log(data.txHash);  // on-chain tx hash (또는 simulation 환경에서 sim_xxx)
+     * ```
+     */
+    refundSession(sessionId: string, params?: RefundSessionParams, opts?: IdempotencyOptions): Promise<ApiResponse<RefundSessionResult>>;
+    /**
+     * Record refund — `status='settled'` 후 머천트가 외부 지갑에서 직접 송금하고 tx_hash를 입력.
+     * 컨트랙트 호출 없음 (DB-only).
+     *
+     * **Idempotency-Key 권장**.
+     *
+     * @example
+     * ```ts
+     * await bitpal.checkout.recordRefund(
+     *   sessionId,
+     *   {
+     *     refund_amount: toAtomicUSDC('5.00'),
+     *     tx_hash: '0xabc...',
+     *     reason: 'manual_offchain_refund',
+     *   },
+     *   { idempotencyKey: randomUUID() },
+     * );
+     * ```
+     */
+    recordRefund(sessionId: string, params: RecordRefundParams, opts?: IdempotencyOptions): Promise<ApiResponse<RefundEntry>>;
+    /** 세션별 환불 내역 (auto + record 통합) */
+    listRefunds(sessionId: string): Promise<ListResponse<RefundEntry>>;
+    /**
+     * CheckoutEscrow에 직접 입금한 외부 결제를 BitPal에 제출·검증.
+     *
+     * Buyer가 merchant UI/SDK에서 `CheckoutEscrow.deposit*()` 함수를 직접 호출한 뒤
+     * 결과 tx_hash를 이 메서드로 제출한다. BitPal은 receipt를 fetch하여
+     * `PaymentDeposited` 이벤트를 검증하고 세션 상태를 갱신한다.
+     *
+     * **인증 방식:**
+     * - Merchant server (API key): `Authorization: Bearer bp_test_*` 헤더 자동 첨부
+     * - Buyer 측 (session_token): `params.session_token` 전달
+     *
+     * @example
+     * ```ts
+     * // Merchant server — API key 인증
+     * const { data } = await bitpal.checkout.submitExternalPayment(sessionId, {
+     *   tx_hash: '0xabc...',
+     *   chain: 'base',
+     * });
+     * console.log(data.validation_status); // 'valid' | 'underpaid' | 'overpaid' | ...
+     * console.log(data.session_status);    // 'paid' | 'unresolved_underpaid' | ...
+     * ```
+     */
+    submitExternalPayment(sessionId: string, params: SubmitExternalPaymentParams, opts?: IdempotencyOptions): Promise<ApiResponse<SubmitExternalPaymentResult>>;
+    /**
+     * Gasless checkout payment through the BitPal API relayer.
+     *
+     * The buyer signs an EIP-3009 authorization and the API calls
+     * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer.
+     * Use the returned session/order state only as immediate UX feedback; the
+     * merchant backend should finalize fulfillment from signed webhooks.
+     */
+    payWithAuthorization(sessionId: string, params: PayWithAuthorizationParams, opts?: IdempotencyOptions): Promise<ApiResponse<CheckoutPaymentResult>>;
+    /**
+     * 세션의 external on-chain 결제 검증 기록 목록 조회.
+     *
+     * `getSession()`의 `payment_observations` 필드와 동일한 데이터를 반환하지만
+     * 검증 기록만 명시적으로 조회할 때 사용한다.
+     *
+     * @example
+     * ```ts
+     * const { data } = await bitpal.checkout.getExternalPaymentStatus(sessionId);
+     * const latest = data[0];
+     * if (latest?.finality_status === 'final_confirmed') {
+     *   // 12 confirmations 완료 — 결제 확정
+     * }
+     * ```
+     */
+    getExternalPaymentStatus(sessionId: string): Promise<ApiResponse<PaymentObservation[]>>;
+    /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
+    previewFee(amount: string): Promise<ApiResponse<FeePreview>>;
+}
+declare class BitPalError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+/**
+ * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
+ *
+ * BitPal backend의 canonical webhook contract와 1:1 정합:
+ *   apps/api/src/services/webhook-canonical-delivery.ts
+ *   apps/api/src/__tests__/webhook-canonical-delivery.test.ts
+ *
+ * 이벤트 명/서명 형식이 backend와 drift하면 머천트 검증이 깨진다.
+ */
+/**
+ * 발송되는 webhook 이벤트 타입.
+ * Backend `services/checkout-webhook.ts:CHECKOUT_WEBHOOK_EVENTS`와 동일 — drift 시
+ * 머천트 코드의 분기 매칭이 실패한다.
+ */
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.session.release_deferred", "checkout.payment.failed", "checkout.payment.finalized", "checkout.payment.revoked", "checkout.refund.recorded", "checkout.refund.completed", "checkout.refund.partial"];
+type CheckoutWebhookEvent = (typeof CHECKOUT_WEBHOOK_EVENTS)[number];
+/**
+ * Canonical envelope (HTTP body).
+ * Backend `CanonicalWebhookEnvelope`와 동일 shape.
+ */
+interface WebhookPayload {
+    /** event_id (replay 시 원본 보존) */
+    id: string;
+    /** canonical event name */
+    event: CheckoutWebhookEvent;
+    /** envelope 생성 시각 (ISO) */
+    created_at: string;
+    /** 이벤트별 payload */
+    data: Record<string, unknown>;
+}
+/** Backend가 보내는 canonical 헤더 이름 */
+declare const WEBHOOK_HEADERS: {
+    readonly signature: "X-Webhook-Signature-256";
+    readonly timestamp: "X-Webhook-Timestamp";
+    readonly event: "X-Webhook-Event";
+    readonly eventId: "X-Webhook-Id";
+    readonly deliveryId: "X-Webhook-Delivery-Id";
+};
+/**
+ * Webhook signature 검증.
+ *
+ * Contract:
+ *  - Backend는 `X-Webhook-Signature-256: sha256=<hex>` 형식으로 보냄
+ *  - 서명 대상은 raw HTTP body (envelope JSON string, byte 단위 동일)
+ *  - HMAC-SHA256(body, secret) hex와 timing-safe compare
+ *
+ * 본 함수는 두 형식 모두 허용하지 않고 canonical(`sha256=<hex>`)만 처리한다.
+ * raw hex만 받는 형식은 폐기됨 (backend 단일 contract).
+ *
+ * @param payload - HTTP request raw body (string)
+ * @param signature - `X-Webhook-Signature-256` 헤더 값 (`sha256=<hex>`)
+ * @param secret - webhook 등록 시 1회 노출된 raw secret (`whsec_...`)
+ * @returns true if signature matches
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { verifyWebhookSignature, parseWebhookEvent, WEBHOOK_HEADERS } from '@bitpal/checkout';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+ *   const sig = req.header(WEBHOOK_HEADERS.signature) ?? '';
+ *   const ok = await verifyWebhookSignature(req.body.toString(), sig, process.env.BITPAL_WEBHOOK_SECRET!);
+ *   if (!ok) return res.status(400).send('invalid signature');
+ *   const event = parseWebhookEvent(req.body.toString());
+ *   if (event.event === 'checkout.session.paid') { ... }
+ *   res.status(200).send('ok');
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+/**
+ * Webhook envelope 파싱.
+ * 형식 검증 후 `WebhookPayload` 타입으로 캐스팅.
+ *
+ * @throws Error 형식이 envelope이 아닐 때
+ */
+declare function parseWebhookEvent(body: string): WebhookPayload;
+
+/**
+ * amount.ts — atomic μUSDC 변환 헬퍼
+ *
+ * BitPal API는 모든 amount를 atomic 정수 문자열로 받는다 (USDC/USDT 6 decimals).
+ *   $1   → "1000000"
+ *   $10  → "10000000"
+ *   $0.5 → "500000"
+ *
+ * 정밀도 손실 방지를 위해 BigInt 연산만 사용한다 (Number 변환 금지 — CLAUDE.md 정책).
+ */
+/**
+ * decimal 문자열 → atomic μUSDC 문자열
+ *
+ * @example
+ * toAtomicUSDC('29.00')   // → '29000000'
+ * toAtomicUSDC('0.5')     // → '500000'
+ * toAtomicUSDC('1000')    // → '1000000000'
+ *
+ * @throws {Error} 음수, 6자리 초과 소수, 형식 오류
+ */
+declare function toAtomicUSDC(decimal: string): string;
+/**
+ * atomic μUSDC 문자열 → 사람이 읽기 좋은 decimal 문자열
+ *
+ * @example
+ * fromAtomicUSDC('29000000')   // → '29.00'
+ * fromAtomicUSDC('500000')     // → '0.50'
+ * fromAtomicUSDC('1500000')    // → '1.50'
+ *
+ * @throws {Error} 정수 문자열이 아니면
+ */
+declare function fromAtomicUSDC(atomic: string): string;
+
+/**
+ * @bitpal/checkout — BitPal Checkout SDK
+ *
+ * 체크아웃 세션 생성, 결제 링크 관리, 수수료 미리보기를 위한 공식 SDK
+ *
+ * @example
+ * ```ts
+ * import { BitPal } from '@bitpal/checkout';
+ *
+ * const bitpal = new BitPal({ apiKey: 'bp_test_...' });
+ *
+ * const { data: session } = await bitpal.checkout.createSession({
+ *   line_items: [{ name: 'Pro Plan', amount: '29.00', currency: 'USDC' }],
+ * });
+ *
+ * console.log(session.url); // 호스티드 결제 페이지 URL
+ * ```
+ */
+
+/**
+ * BitPal SDK 메인 엔트리
+ */
+declare class BitPal {
+    readonly checkout: BitPalCheckoutClient;
+    constructor(config: BitPalConfig | string);
+}
+
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutPaymentResult, type CheckoutSession, type CheckoutWebhookEvent, type CreateSessionParams, type ExternalPaymentConfig, type FeePreview, type IdempotencyOptions, type LineItem, type ListResponse, type PayWithAuthorizationParams, type PaymentObservation, type RecordRefundParams, type RefundEntry, type RefundSessionParams, type RefundSessionResult, type SubmitExternalPaymentParams, type SubmitExternalPaymentResult, WEBHOOK_HEADERS, type WebhookPayload, fromAtomicUSDC, parseWebhookEvent, toAtomicUSDC, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,325 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.bitpal.io";
+var DEFAULT_TIMEOUT = 3e4;
+var BitPalCheckoutClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  constructor(config) {
+    if (!config.apiKey) throw new Error("apiKey is required");
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+  /* ─── 내부 HTTP ─── */
+  async request(method, path, body, extraHeaders) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          ...extraHeaders ?? {}
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const json = await res.json();
+      if (!res.ok) {
+        const msg = json.error ?? `HTTP ${res.status}`;
+        throw new BitPalError(String(msg), res.status);
+      }
+      return json;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /* ─── Sessions ─── */
+  /**
+   * 체크아웃 세션 생성.
+   *
+   * 모든 `line_items[].amount`는 atomic μUSDC 정수 문자열이어야 한다 ($1 = "1000000").
+   * decimal 표기는 거부된다 — `toAtomicUSDC()` 헬퍼 사용 권장.
+   *
+   * @example
+   * import { BitPal, toAtomicUSDC } from '@bitpal/checkout';
+   * const bp = new BitPal('bp_test_...');
+   * const { data } = await bp.checkout.createSession({
+   *   line_items: [{ name: 'Pro', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
+   * });
+   * console.log(data.url); // → buyer를 redirect할 결제 페이지
+   */
+  async createSession(params) {
+    const res = await this.request(
+      "POST",
+      "/v1/checkout/sessions",
+      params
+    );
+    if (res.data) {
+      if (res.data.checkout_url) {
+        res.data.url = res.data.checkout_url;
+      } else if (!res.data.url) {
+        res.data.url = `${this.baseUrl.replace("api.", "")}/pay/${res.data.id}`;
+      }
+    }
+    return res;
+  }
+  /** 세션 조회 */
+  async getSession(sessionId) {
+    return this.request(
+      "GET",
+      `/v1/checkout/sessions/${sessionId}`
+    );
+  }
+  /** 세션 목록 조회 */
+  async listSessions(params) {
+    const qs = new URLSearchParams();
+    if (params?.status) qs.set("status", params.status);
+    if (params?.limit) qs.set("limit", String(params.limit));
+    if (params?.offset) qs.set("offset", String(params.offset));
+    const query = qs.toString();
+    return this.request(
+      "GET",
+      `/v1/checkout/sessions${query ? `?${query}` : ""}`
+    );
+  }
+  /* ─── Refunds ─── */
+  /**
+   * Auto refund — escrow 보관 중일 때 컨트랙트가 buyer에게 직접 transfer.
+   *
+   * `params.amount` 미지정 시 backend가 잔액 전액(`type: 'full'`). 명시 시 `type: 'partial'`.
+   * **Idempotency-Key 권장** — 같은 키로 재시도 시 backend가 같은 결과 반환.
+   *
+   * 머천트가 `frozen` 상태면 환불은 허용되지만, `suspended` 상태에서는 차단된다.
+   *
+   * @example
+   * ```ts
+   * import { randomUUID } from 'node:crypto';
+   * const { data } = await bitpal.checkout.refundSession(
+   *   sessionId,
+   *   { amount: toAtomicUSDC('5.00'), reason: 'customer_requested' },
+   *   { idempotencyKey: randomUUID() },
+   * );
+   * console.log(data.txHash);  // on-chain tx hash (또는 simulation 환경에서 sim_xxx)
+   * ```
+   */
+  async refundSession(sessionId, params = {}, opts) {
+    return this.request(
+      "POST",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/refund`,
+      params,
+      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
+    );
+  }
+  /**
+   * Record refund — `status='settled'` 후 머천트가 외부 지갑에서 직접 송금하고 tx_hash를 입력.
+   * 컨트랙트 호출 없음 (DB-only).
+   *
+   * **Idempotency-Key 권장**.
+   *
+   * @example
+   * ```ts
+   * await bitpal.checkout.recordRefund(
+   *   sessionId,
+   *   {
+   *     refund_amount: toAtomicUSDC('5.00'),
+   *     tx_hash: '0xabc...',
+   *     reason: 'manual_offchain_refund',
+   *   },
+   *   { idempotencyKey: randomUUID() },
+   * );
+   * ```
+   */
+  async recordRefund(sessionId, params, opts) {
+    return this.request(
+      "POST",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/record-refund`,
+      params,
+      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
+    );
+  }
+  /** 세션별 환불 내역 (auto + record 통합) */
+  async listRefunds(sessionId) {
+    return this.request(
+      "GET",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/refunds`
+    );
+  }
+  /* ─── External On-chain Payments ─── */
+  /**
+   * CheckoutEscrow에 직접 입금한 외부 결제를 BitPal에 제출·검증.
+   *
+   * Buyer가 merchant UI/SDK에서 `CheckoutEscrow.deposit*()` 함수를 직접 호출한 뒤
+   * 결과 tx_hash를 이 메서드로 제출한다. BitPal은 receipt를 fetch하여
+   * `PaymentDeposited` 이벤트를 검증하고 세션 상태를 갱신한다.
+   *
+   * **인증 방식:**
+   * - Merchant server (API key): `Authorization: Bearer bp_test_*` 헤더 자동 첨부
+   * - Buyer 측 (session_token): `params.session_token` 전달
+   *
+   * @example
+   * ```ts
+   * // Merchant server — API key 인증
+   * const { data } = await bitpal.checkout.submitExternalPayment(sessionId, {
+   *   tx_hash: '0xabc...',
+   *   chain: 'base',
+   * });
+   * console.log(data.validation_status); // 'valid' | 'underpaid' | 'overpaid' | ...
+   * console.log(data.session_status);    // 'paid' | 'unresolved_underpaid' | ...
+   * ```
+   */
+  async submitExternalPayment(sessionId, params, opts) {
+    return this.request(
+      "POST",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/submit-external-payment`,
+      params,
+      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
+    );
+  }
+  /**
+   * Gasless checkout payment through the BitPal API relayer.
+   *
+   * The buyer signs an EIP-3009 authorization and the API calls
+   * `CheckoutEscrow.depositWithAuthorization()` with the platform relayer.
+   * Use the returned session/order state only as immediate UX feedback; the
+   * merchant backend should finalize fulfillment from signed webhooks.
+   */
+  async payWithAuthorization(sessionId, params, opts) {
+    return this.request(
+      "POST",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/submit-payment`,
+      params,
+      opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0
+    );
+  }
+  /**
+   * 세션의 external on-chain 결제 검증 기록 목록 조회.
+   *
+   * `getSession()`의 `payment_observations` 필드와 동일한 데이터를 반환하지만
+   * 검증 기록만 명시적으로 조회할 때 사용한다.
+   *
+   * @example
+   * ```ts
+   * const { data } = await bitpal.checkout.getExternalPaymentStatus(sessionId);
+   * const latest = data[0];
+   * if (latest?.finality_status === 'final_confirmed') {
+   *   // 12 confirmations 완료 — 결제 확정
+   * }
+   * ```
+   */
+  async getExternalPaymentStatus(sessionId) {
+    return this.request(
+      "GET",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/payment-observations`
+    );
+  }
+  /* ─── Fees ─── */
+  /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
+  async previewFee(amount) {
+    return this.request(
+      "GET",
+      `/v1/checkout/fee-preview?amount=${encodeURIComponent(amount)}`
+    );
+  }
+};
+var BitPalError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "BitPalError";
+    this.statusCode = statusCode;
+  }
+};
+
+// src/webhook.ts
+var CHECKOUT_WEBHOOK_EVENTS = [
+  "checkout.session.created",
+  "checkout.session.paid",
+  "checkout.session.settled",
+  "checkout.session.expired",
+  "checkout.session.unresolved",
+  "checkout.session.release_deferred",
+  "checkout.payment.failed",
+  "checkout.payment.finalized",
+  "checkout.payment.revoked",
+  "checkout.refund.recorded",
+  "checkout.refund.completed",
+  "checkout.refund.partial"
+];
+var WEBHOOK_HEADERS = {
+  signature: "X-Webhook-Signature-256",
+  timestamp: "X-Webhook-Timestamp",
+  event: "X-Webhook-Event",
+  eventId: "X-Webhook-Id",
+  deliveryId: "X-Webhook-Delivery-Id"
+};
+var SIGNATURE_PREFIX = "sha256=";
+async function verifyWebhookSignature(payload, signature, secret) {
+  if (!payload || !signature || !secret) return false;
+  if (!signature.startsWith(SIGNATURE_PREFIX)) return false;
+  const sigHex = signature.slice(SIGNATURE_PREFIX.length);
+  if (!/^[0-9a-f]+$/.test(sigHex)) return false;
+  try {
+    const crypto = await import("crypto");
+    const expectedHex = crypto.createHmac("sha256", secret).update(payload, "utf8").digest("hex");
+    if (sigHex.length !== expectedHex.length) return false;
+    return crypto.timingSafeEqual(
+      Buffer.from(sigHex, "hex"),
+      Buffer.from(expectedHex, "hex")
+    );
+  } catch {
+    return false;
+  }
+}
+function parseWebhookEvent(body) {
+  const parsed = JSON.parse(body);
+  if (typeof parsed.id !== "string" || typeof parsed.event !== "string" || typeof parsed.created_at !== "string" || typeof parsed.data !== "object" || parsed.data === null) {
+    throw new Error("Invalid webhook envelope \u2014 expected {id, event, created_at, data}");
+  }
+  return parsed;
+}
+
+// src/amount.ts
+var USDC_DECIMALS = 6n;
+var USDC_SCALE = 10n ** USDC_DECIMALS;
+function toAtomicUSDC(decimal) {
+  if (typeof decimal !== "string" || !/^\d+(\.\d{1,6})?$/.test(decimal)) {
+    throw new Error(`toAtomicUSDC: invalid decimal '${decimal}' (max 6 fractional digits, no negatives)`);
+  }
+  const [whole, frac = ""] = decimal.split(".");
+  const fracPadded = frac.padEnd(Number(USDC_DECIMALS), "0");
+  return (BigInt(whole) * USDC_SCALE + BigInt(fracPadded || "0")).toString();
+}
+function fromAtomicUSDC(atomic) {
+  if (typeof atomic !== "string" || !/^\d+$/.test(atomic)) {
+    throw new Error(`fromAtomicUSDC: invalid atomic '${atomic}' (must be non-negative integer string)`);
+  }
+  const big = BigInt(atomic);
+  const whole = big / USDC_SCALE;
+  const frac = big % USDC_SCALE;
+  const fracStr = frac.toString().padStart(Number(USDC_DECIMALS), "0").replace(/0+$/, "");
+  return fracStr.length > 0 ? `${whole}.${fracStr.padEnd(2, "0")}` : `${whole}.00`;
+}
+
+// src/index.ts
+var BitPal = class {
+  checkout;
+  constructor(config) {
+    const cfg = typeof config === "string" ? { apiKey: config } : config;
+    this.checkout = new BitPalCheckoutClient(cfg);
+  }
+};
+export {
+  BitPal,
+  BitPalCheckoutClient,
+  BitPalError,
+  CHECKOUT_WEBHOOK_EVENTS,
+  WEBHOOK_HEADERS,
+  fromAtomicUSDC,
+  parseWebhookEvent,
+  toAtomicUSDC,
+  verifyWebhookSignature
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bitpal/checkout",
+  "version": "0.1.0",
+  "description": "BitPal Checkout SDK — crypto payment sessions, external on-chain payment verification, gasless checkout, refunds, fee preview.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "bitpal",
+    "checkout",
+    "crypto",
+    "usdc",
+    "payments",
+    "sdk",
+    "evm",
+    "base",
+    "stablecoin",
+    "escrow"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.9"
+  }
+}