@bitpal/checkout 0.2.0 → 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,566 @@
+/**
+ * @bitpal/checkout SDK — 타입 정의
+ */
+interface BitPalConfig {
+    /**
+     * API 키(서버 전용, secret). prefix 가 mode 를 결정합니다:
+     *   - `bp_test_...` → TEST mode (testnet 또는 local anvil)
+     *   - `bp_live_...` → LIVE mode (mainnet)
+     *
+     * BitPal 콘솔 → Developers → API Keys 에서 발급.
+     *
+     * **선택**: createSession/listSessions/products 등 서버 메서드는 필수. 그러나 buyer-facing 공개 메서드
+     * (getPublicSession/getStatus/issueDepositAddress)는 인증 불요(session_token 기반)이므로 브라우저에서
+     * apiKey 없이 쓸 수 있다 — 절대 secret 키를 브라우저에 노출하지 말 것.
+     */
+    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 PriceLineItem {
+    /** price_... — bitpal.checkout.prices.create()로 만든 가격 */
+    price_id: string;
+    quantity?: number;
+}
+type CheckoutLineItemInput = LineItem | PriceLineItem;
+interface CreateSessionParams {
+    line_items: CheckoutLineItemInput[];
+    /** 고객 지갑 주소 (선택) */
+    payer_wallet?: string;
+    /** 결제 체인 (예: eip155:8453). 단일 고정 — allowed_pay_chains와 상호 배타. */
+    pay_chain?: string;
+    /**
+     * 허용 결제 체인 목록 (CAIP-2). 구매자가 이 중에서 선택하며, 하나뿐이면 자동 선택된다.
+     * pay_chain(단일 고정)과 **상호 배타** — 동시 지정 시 SDK가 에러를 throw한다.
+     * 예: ['eip155:84532', 'eip155:11155420', 'eip155:80002', 'eip155:421614']
+     */
+    allowed_pay_chains?: 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' — 결제 경로. hosted deposit-address 단일 경로. */
+    payment_source?: string;
+    /** 호스티드 결제 페이지 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;
+}
+/**
+ * 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
+ * `issueDepositAddress({ chain, token })` 로 입금주소를 발급받는다. 단일-자산 세션은 1개.
+ */
+interface PaymentOption {
+    /** CAIP-2 (예: eip155:8453) */
+    caip2: string;
+    chain_id: number;
+    token_symbol: string;
+    token_address: string;
+}
+/**
+ * `getPublicSession()` (`GET /v1/checkout/sessions/:id/public`) 응답 — 인증 불요(공개).
+ * buyer-facing 결제 페이지가 표시/폴링에 쓰는 서버 권위 뷰.
+ */
+interface PublicSession {
+    id: string;
+    /** created | awaiting_deposit | deposit_detected | paid_confirmed | swept | unresolved_* | wrong_token | expired ... */
+    status: string;
+    mode: string | null;
+    currency: string;
+    /** Atomic 정수 문자열(토큰 decimals 기준). */
+    amount_total: string;
+    amount_received?: string | null;
+    pay_chain: string | null;
+    pay_asset: string | null;
+    /** 발급된 주문별 forwarder 입금주소(미발급이면 null). */
+    deposit_address?: string | null;
+    /** 구매자 선택 가능한 결제 옵션(서버 권위). 단일-자산이면 1개. */
+    payment_options: PaymentOption[];
+    chain_id: number | null;
+    token_address: string | null;
+    tx_hash: string | null;
+    release_tx_hash?: string | null;
+    expires_at: string | null;
+    success_url: string | null;
+    cancel_url: string | null;
+    fee_amount: string | null;
+    net_amount: string | null;
+    seller_wallet: string;
+    paid_at: string | null;
+    settled_at: string | null;
+    created_at: string;
+    line_items: LineItem[];
+}
+/**
+ * `issueDepositAddress()` 요청 파라미터.
+ * chain/token 은 멀티옵션 세션에서만 필요(단일-자산 세션은 생략). refundAddress 는 필수 —
+ * 금액부족/잘못된토큰/만료 시 이 주소로 환불되며, 입금주소에 커밋되어 발급 후 변경 불가.
+ */
+interface IssueDepositAddressParams {
+    /** 결제 페이지 접근 증명(HMAC). createSession 응답의 session_token. */
+    session_token: string;
+    /** 환불 주소(0x EVM). 필수. */
+    refundAddress: string;
+    /** 선택 자산의 chain(CAIP-2 또는 short-name). 멀티옵션 세션 필수. */
+    chain?: string;
+    /** 선택 자산의 token symbol(예: USDC). 멀티옵션 세션 필수. */
+    token?: string;
+}
+/**
+ * `issueDepositAddress()` 응답 — 이 주소로 정확 금액을 송금하면 watcher 가 감지, keeper 가 정산한다.
+ */
+interface DepositAddress {
+    sessionId: string;
+    chain: string;
+    /** 주문별 CREATE2 forwarder 입금주소. */
+    depositAddress: string;
+    expectedToken: string;
+    /** Atomic 정수 문자열. */
+    expectedAmount: string;
+    feeAmount: string;
+    refundAddress: string;
+    /** Unix seconds — on-chain deadline. */
+    deadline: string;
+    expiresAt: string | null;
+}
+/**
+ * `getStatus()` (`GET /v1/checkout/sessions/:id/status`) 응답 — 경량 폴링용(인증 불요).
+ */
+interface SessionStatus {
+    status: string;
+    paid_at: string | null;
+}
+/**
+ * 수수료 미리보기 응답.
+ * 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;
+}
+/**
+ * 환불은 온체인 자동 경로 — SDK 에 수동 환불 API 는 없다.
+ * 금액부족/잘못된토큰/만료 시 issueDepositAddress 에 지정한 refundAddress 로 자동 환불되고,
+ * 세션 status(expired/unresolved) + webhook 으로 통지된다.
+ */
+/**
+ * 멱등성 키 — 동일 키로 재시도 시 backend가 같은 결과 반환.
+ */
+interface IdempotencyOptions {
+    idempotencyKey?: string;
+}
+interface ApiResponse<T> {
+    data: T;
+    error?: string;
+}
+interface ListResponse<T> {
+    data: T[];
+    total?: number;
+}
+interface CheckoutProduct {
+    /** prod_... */
+    id: string;
+    name: string;
+    description: string | null;
+    image_url: string | null;
+    /** 'active' | 'inactive' */
+    status: string;
+    metadata: Record<string, unknown>;
+    mode: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CheckoutPrice {
+    /** price_... */
+    id: string;
+    /** prod_... */
+    product_id: string;
+    /** 원자 단위 정수 문자열 ($1 = "1000000") — 불변 */
+    amount_atomic: string;
+    currency: string;
+    token_symbol: string;
+    /** v1: 'one_time' */
+    billing_type: string;
+    nickname: string | null;
+    lookup_key: string | null;
+    mode: string;
+    created_at: string;
+}
+interface CreateProductParams {
+    name: string;
+    description?: string;
+    image_url?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateProductParams {
+    name?: string;
+    description?: string | null;
+    image_url?: string | null;
+    metadata?: Record<string, unknown>;
+    status?: 'active' | 'inactive';
+}
+interface CreatePriceParams {
+    /** 원자 단위 정수 문자열 ($1 = "1000000"). `toAtomicUSDC('1.00')` 헬퍼 사용 권장 */
+    amount_atomic: string;
+    currency?: string;
+    token_symbol?: string;
+    billing_type?: 'one_time';
+    nickname?: string;
+    lookup_key?: string;
+}
+/**
+ * Price는 lifecycle 없는 immutable record — 변경 가능한 것은 nickname(표시 메타)뿐.
+ * 금액류 필드(amount_atomic 등)는 immutable, "그만 팔기"는 Price 가 아니라 그 Price 를 쓰는
+ * Payment Link 를 inactive 로 한다.
+ */
+interface UpdatePriceParams {
+    nickname?: string | null;
+}
+interface ListProductsParams {
+    status?: 'active' | 'inactive';
+    limit?: number;
+    offset?: number;
+}
+interface ListPricesParams {
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * catalog.ts — Product / immutable Price 관리 리소스 (PROD-LINK-3a-SDK)
+ *
+ * server-side SDK 전용 (secret API key). 브라우저에서 사용 금지.
+ *
+ * 사용 예:
+ * ```ts
+ * const bitpal = new BitPal({ apiKey: 'bp_test_...' });
+ * const { data: product } = await bitpal.checkout.products.create({ name: 'Pro Plan' });
+ * const { data: price } = await bitpal.checkout.prices.create(product.id, {
+ *   amount_atomic: toAtomicUSDC('29.00'),
+ * });
+ * ```
+ *
+ * Price immutable 원칙: 가격 변경은 update가 아니라 "새 price 생성"이다.
+ * `prices.update`는 nickname(표시 메타)만 받는다 — 금액류 필드 변경 helper는 의도적으로 없다.
+ * "그만 팔기"는 Price 를 끄는 게 아니라 그 Price 를 쓰는 Payment Link 를 inactive 로 한다.
+ */
+
+/** client.ts의 private request를 리소스에 주입하기 위한 시그니처 */
+type CatalogRequester = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+declare class ProductsResource {
+    private readonly request;
+    constructor(request: CatalogRequester);
+    /** POST /v1/checkout/products */
+    create(params: CreateProductParams): Promise<ApiResponse<CheckoutProduct>>;
+    /** GET /v1/checkout/products */
+    list(params?: ListProductsParams): Promise<ListResponse<CheckoutProduct>>;
+    /** GET /v1/checkout/products/:id */
+    retrieve(productId: string): Promise<ApiResponse<CheckoutProduct>>;
+    /** PATCH /v1/checkout/products/:id */
+    update(productId: string, params: UpdateProductParams): Promise<ApiResponse<CheckoutProduct>>;
+}
+declare class PricesResource {
+    private readonly request;
+    constructor(request: CatalogRequester);
+    /** POST /v1/checkout/products/:id/prices */
+    create(productId: string, params: CreatePriceParams): Promise<ApiResponse<CheckoutPrice>>;
+    /** GET /v1/checkout/products/:id/prices */
+    list(productId: string, params?: ListPricesParams): Promise<ListResponse<CheckoutPrice>>;
+    /** GET /v1/checkout/prices/:id */
+    retrieve(priceId: string): Promise<ApiResponse<CheckoutPrice>>;
+    /**
+     * PATCH /v1/checkout/prices/:id — nickname(표시 메타)만.
+     * 금액류 필드(amount_atomic 등)는 immutable — 서버가 PRICE_IMMUTABLE_FIELD로 거부한다.
+     * 가격 변경은 `prices.create()`로 새 price를 만들 것. "그만 팔기"는 해당 Price 를 쓰는
+     * Payment Link 를 inactive 로 한다(Price 자체에는 active/inactive 개념이 없다).
+     */
+    update(priceId: string, params: UpdatePriceParams): Promise<ApiResponse<CheckoutPrice>>;
+}
+
+/**
+ * @bitpal/checkout SDK — 클라이언트
+ *
+ * Phase 1 범위: 세션 생성/조회, 결제 링크 생성/조회, 수수료 미리보기.
+ * 크레딧 잔액/충전은 BitPal non-custodial 모델에서 제거됨.
+ */
+
+declare class BitPalCheckoutClient {
+    /** 서버 메서드용 secret 키. 공개(buyer-facing) 메서드는 없이도 동작. */
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /** PROD-LINK-3a-SDK: Product 카탈로그 관리 (server-side 전용) */
+    readonly products: ProductsResource;
+    /** PROD-LINK-3a-SDK: immutable Price 관리 — 가격 변경은 비활성화 + 새 price 생성 */
+    readonly prices: PricesResource;
+    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할 결제 페이지
+     *
+     * // 멀티체인 허용 — 구매자가 Base/Optimism 중 선택(하나뿐이면 자동 선택):
+     * await bp.checkout.createSession({
+     *   line_items: [{ name: 'Pro', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
+     *   allowed_pay_chains: ['eip155:84532', 'eip155:11155420'],
+     * });
+     * // 단일 체인 고정은 pay_chain 사용(둘은 상호 배타).
+     */
+    createSession(params: CreateSessionParams): Promise<ApiResponse<CheckoutSession>>;
+    /** 세션 조회 */
+    getSession(sessionId: string): Promise<ApiResponse<CheckoutSession>>;
+    /** 세션 목록 조회 */
+    listSessions(params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListResponse<CheckoutSession>>;
+    /**
+     * 공개 세션 조회 (`GET /v1/checkout/sessions/:id/public`) — 인증 불요.
+     *
+     * buyer-facing 결제 페이지가 표시/자산선택에 쓰는 서버 권위 뷰. `payment_options` 로
+     * 구매자 선택 가능한 chain×token 을 얻고, 발급 후에는 `deposit_address` 가 채워진다.
+     */
+    getPublicSession(sessionId: string): Promise<ApiResponse<PublicSession>>;
+    /**
+     * 주문별 비수탁 입금주소 발급 (`POST /v1/checkout/sessions/:id/deposit-address`).
+     *
+     * 비수탁 결제 진입점. 구매자가 자산(멀티옵션이면 chain/token)과 환불 주소를 확정하면 서버가
+     * 그 주문 전용 CREATE2 forwarder 주소를 돌려준다. 구매자는 아무 지갑/거래소에서 **정확한 금액**을
+     * 그 주소로 일반 송금하면 된다(서명·연결 불필요). watcher 가 감지 → keeper 가 정산.
+     *
+     * refundAddress 는 입금주소에 커밋되어 발급 후 변경 불가. session_token 은 createSession 응답값.
+     *
+     * @example
+     * ```ts
+     * const { data } = await bitpal.checkout.issueDepositAddress(sessionId, {
+     *   session_token: session.session_token!,
+     *   refundAddress: '0xBuyerWallet...',
+     *   chain: 'eip155:8453', // 멀티옵션 세션만 필요
+     *   token: 'USDC',
+     * });
+     * console.log(data.depositAddress, data.expectedAmount); // 이 주소로 정확 금액 송금
+     * ```
+     */
+    issueDepositAddress(sessionId: string, params: IssueDepositAddressParams): Promise<ApiResponse<DepositAddress>>;
+    /**
+     * 경량 상태 폴링 (`GET /v1/checkout/sessions/:id/status`) — 인증 불요.
+     *
+     * status: awaiting_deposit → deposit_detected → paid_confirmed/swept. 확정/정산은 webhook 으로도
+     * 통지되므로, 서버 사이드 확정은 webhook 을 신뢰(폴링은 buyer UX 용).
+     */
+    getStatus(sessionId: string): Promise<ApiResponse<SessionStatus>>;
+    /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
+    previewFee(amount: string): Promise<ApiResponse<FeePreview>>;
+}
+declare class BitPalError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+/**
+ * @bitpal/checkout — Webhook 서명 검증 + 이벤트 타입
+ *
+ * BitPal 이 보내는 canonical webhook contract(envelope/서명/헤더)와 1:1 정합한다.
+ */
+/**
+ * BitPal 이 발송하는 webhook 이벤트 타입 전체 목록.
+ */
+declare const CHECKOUT_WEBHOOK_EVENTS: readonly ["checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded"];
+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 raw = req.body.toString('utf8'); // raw body — parse/re-serialize 하면 서명 깨짐
+ *   const ok = await verifyWebhookSignature(
+ *     raw,
+ *     req.header(WEBHOOK_HEADERS.signature) ?? '',
+ *     process.env.BITPAL_WEBHOOK_SECRET!,
+ *     { timestamp: req.header(WEBHOOK_HEADERS.timestamp) ?? '' }, // replay 방어 — 필수
+ *   );
+ *   if (!ok) return res.status(400).send('invalid signature');
+ *   const event = parseWebhookEvent(raw);
+ *   // dedup 은 서명된 body 의 event.id 로 (헤더 X-Webhook-Id 는 미서명)
+ *   if (await alreadyProcessed(event.id)) return res.status(200).send('dup');
+ *   if (event.event === 'checkout.session.paid') { ... }
+ *   res.status(200).send('ok');
+ * });
+ * ```
+ */
+interface VerifyWebhookOptions {
+    /** `X-Webhook-Timestamp` 헤더 값(ISO UTC). 서명 대상에 포함되며 freshness 검사에 쓰인다. 필수. */
+    timestamp: string;
+    /** freshness 허용 오차(초). 기본 300(5분). |now - timestamp| 초과 시 replay 로 간주해 거부. */
+    toleranceSec?: number;
+}
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string, opts?: VerifyWebhookOptions): 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({
+ *   // amount 는 원자 단위 μUSDC 문자열(6 decimals). $29.00 → '29000000'. toAtomicUSDC 사용 권장.
+ *   line_items: [{ name: 'Pro Plan', amount: toAtomicUSDC('29.00'), currency: 'USDC' }],
+ * });
+ *
+ * console.log(session.url); // 호스티드 결제 페이지 URL (checkout_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 CheckoutLineItemInput, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type DepositAddress, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPricesParams, type ListProductsParams, type ListResponse, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, fromAtomicUSDC, parseWebhookEvent, toAtomicUSDC, verifyWebhookSignature };