@bitpal/checkout 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -0,0 +1,708 @@
+/**
+ * @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;
+}
+/** 응답/정규화된 line item — amount 는 항상 atomic μUSD 정수. */
+interface LineItem {
+    name: string;
+    /** Atomic μUSD 정수 문자열($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")인 경우(고급/기존 코드).
+ * 둘 다 지정하거나 둘 다 생략하면 SDK 가 에러를 throw 한다.
+ */
+interface LineItemInput {
+    name: string;
+    currency: string;
+    quantity?: number;
+    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    amount?: string;
+    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    amount_atomic?: string;
+}
+interface PriceLineItem {
+    /** price_... — bitpal.checkout.prices.create()로 만든 가격 */
+    price_id: string;
+    quantity?: number;
+}
+type CheckoutLineItemInput = LineItemInput | 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' — 결제 경로. 안2 는 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;
+}
+/**
+ * 안2 결제 옵션(chain×token). `/public` 이 서버 권위로 내려주며, buyer 가 하나를 골라
+ * `issueDepositAddress({ chain, token })` 로 입금주소를 발급받는다. 단일-자산 세션은 1개.
+ */
+interface PaymentOption {
+    /** CAIP-2 (예: eip155:8453, tron:0x2b6653dc, solana:5eykt4…). 체인 식별의 canonical. */
+    caip2: string;
+    /** EVM numeric chainId. 비-EVM(Tron/Solana)은 null — 식별은 caip2 사용. */
+    chain_id: number | null;
+    token_symbol: string;
+    /** 토큰 컨트랙트/mint 주소(EVM 0x / Tron base58 / Solana base58 mint). */
+    token_address: string;
+    /** 토큰 decimals(USDC/USDT=6, BSC-USD=18). atomic↔decimal 변환에 필수 — 6dp 가정 금지. */
+    decimals: number;
+}
+/**
+ * `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;
+    /** 선택된 pay 토큰 decimals(발급 후). amount_total/amount_received atomic 해석에 사용 — 6dp 가정 금지. */
+    token_decimals?: number | 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;
+    /**
+     * 환불 주소. 필수. 선택한 체인의 VM 형식이어야 한다:
+     *   EVM=0x…, Tron=base58(T…), Solana=base58. 결제와 같은 네트워크의 본인 주소.
+     * 금액부족/잘못된토큰/만료 시 이 주소로 환불되며, 입금주소에 커밋되어 발급 후 변경 불가.
+     */
+    refundAddress: string;
+    /** 선택 자산의 chain(CAIP-2 또는 short-name). 멀티옵션 세션 필수. */
+    chain?: string;
+    /** 선택 자산의 token symbol(예: USDC). 멀티옵션 세션 필수. */
+    token?: string;
+}
+/**
+ * `issueDepositAddress()` 응답 — 이 주소로 정확 금액을 송금하면 watcher 가 감지, keeper 가 정산한다.
+ */
+interface DepositAddress {
+    sessionId: string;
+    chain: string;
+    /** 주문별 결정적 입금주소(EVM/Tron=CREATE2 forwarder, Solana=order PDA 의 deposit ATA). */
+    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';
+}
+/**
+ * 가격 생성 입력. 금액은 둘 중 **하나** (line item 과 동일 모델):
+ *   - `amount`(권장): 사람 표기 USD 문자열(예 "29", "0.5"). decimal 신경 쓸 필요 없음.
+ *   - `amount_atomic`: raw μUSD 정수($1="1000000") — 고급/기존.
+ * 둘 다 지정하거나 둘 다 생략하면 서버가 400 을 반환한다.
+ */
+interface CreatePriceParams {
+    /** 사람 표기 USD 금액(예 "29", "0.5") — 권장. amount_atomic 과 상호배타. */
+    amount?: string;
+    /** raw μUSD 정수($1="1000000") — 고급/기존. amount 와 상호배타. */
+    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;
+}
+interface CheckoutPaymentLink {
+    /** plink_... */
+    id: string;
+    /** 고엔트로피 공개 토큰 — 호스티드 URL `{checkoutBase}/plink/{share_token}` 에 사용 */
+    share_token: string;
+    /** price_... — 이 링크가 파는 가격(생성 후 고정) */
+    price_id: string;
+    title: string | null;
+    description: string | null;
+    collect_email: boolean;
+    email_required: boolean;
+    /** CAIP-2 목록 또는 null(legacy) */
+    allowed_pay_chains: string[] | null;
+    /** chain×token cell 목록 또는 null */
+    allowed_assets: Array<{
+        caip2: string;
+        token: string;
+    }> | null;
+    success_url: string | null;
+    cancel_url: string | null;
+    /** 'active' | 'inactive' */
+    status: string;
+    max_uses: number | null;
+    paid_use_count: number;
+    expires_at: string | null;
+    mode: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreatePaymentLinkParams {
+    /** price_... — bitpal.checkout.prices.create() 로 만든 가격. 필수. */
+    price_id: string;
+    title?: string;
+    description?: string;
+    /** buyer 이메일 수집(기본 true) */
+    collect_email?: boolean;
+    /** buyer 이메일 필수(기본 true). true 면 collect_email 도 true 여야 함. */
+    email_required?: boolean;
+    /** 허용 결제 체인(CAIP-2 또는 short-name). allowed_assets 가 있으면 그쪽 우선. */
+    allowed_pay_chains?: string[];
+    /** chain×token cell 허용 목록 — allowed_pay_chains 보다 우선. */
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }>;
+    success_url?: string;
+    cancel_url?: string;
+    max_uses?: number;
+    /** ISO-8601 datetime */
+    expires_at?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdatePaymentLinkParams {
+    title?: string | null;
+    description?: string | null;
+    collect_email?: boolean;
+    email_required?: boolean;
+    allowed_pay_chains?: string[] | null;
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }> | null;
+    success_url?: string | null;
+    cancel_url?: string | null;
+    status?: 'active' | 'inactive';
+    max_uses?: number | null;
+    expires_at?: string | null;
+    metadata?: Record<string, unknown>;
+}
+interface ListPaymentLinksParams {
+    status?: 'active' | 'inactive';
+    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>>;
+}
+/**
+ * Payment Link 리소스 — 대시보드 없이 코드로 결제 링크 생성/관리 (PROD-LINK-4).
+ *
+ * 흐름: product 생성 → price 생성 → payment link 생성. link↔price binding 은 생성 후 고정.
+ *
+ * ```ts
+ * const { data: product } = await bitpal.checkout.products.create({ name: 'Pro Plan' });
+ * const { data: price }   = await bitpal.checkout.prices.create(product.id, { amount: '29' });
+ * const { data: link }    = await bitpal.checkout.paymentLinks.create({
+ *   price_id: price.id,
+ *   allowed_pay_chains: ['eip155:8453', 'solana:5eykt4Us…'],
+ * });
+ * // 호스티드 결제 페이지 URL: `{checkoutBase}/plink/${link.share_token}`
+ * ```
+ */
+declare class PaymentLinksResource {
+    private readonly request;
+    constructor(request: CatalogRequester);
+    /** POST /v1/checkout/payment-links */
+    create(params: CreatePaymentLinkParams): Promise<ApiResponse<CheckoutPaymentLink>>;
+    /** GET /v1/checkout/payment-links */
+    list(params?: ListPaymentLinksParams): Promise<ListResponse<CheckoutPaymentLink>>;
+    /** GET /v1/checkout/payment-links/:id */
+    retrieve(linkId: string): Promise<ApiResponse<CheckoutPaymentLink>>;
+    /** PATCH /v1/checkout/payment-links/:id */
+    update(linkId: string, params: UpdatePaymentLinkParams): Promise<ApiResponse<CheckoutPaymentLink>>;
+}
+
+/**
+ * @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;
+    /** PROD-LINK-4-SDK: Payment Link 관리 — 대시보드 없이 코드로 결제 링크 생성 (server-side 전용) */
+    readonly paymentLinks: PaymentLinksResource;
+    constructor(config: BitPalConfig);
+    private request;
+    /**
+     * 체크아웃 세션 생성.
+     *
+     * `line_items[].amount` 는 사람 표기 USD 문자열("29", "0.5") — decimal 계산 불필요.
+     * 이미 raw μUSD 정수라면 `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 무관.
+     *   line_items: [{ name: 'Pro', amount: '29', currency: 'USDC' }],
+     * });
+     * console.log(data.url); // → buyer를 redirect할 결제 페이지
+     *
+     * // 멀티체인 허용 — 구매자가 Base/Optimism 중 선택(하나뿐이면 자동 선택):
+     * //   어떤 체인·토큰이든 amount 그대로 — 서버가 발급 시 토큰 decimals 로 재스케일.
+     * await bp.checkout.createSession({
+     *   line_items: [{ name: 'Pro', amount: '29', 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`).
+     *
+     * 안2 결제 진입점. 구매자가 자산(멀티옵션이면 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 ↔ decimal 변환 헬퍼 (임의 decimals + USDC 하위호환)
+ *
+ * BitPal API는 모든 amount를 atomic 정수 문자열로 받는다. decimals 는 토큰마다 다르다:
+ *   USDC/USDT(Base/Arb/Tron/Solana) = 6, BSC-USD(BNB USDT) = 18. → payment_options[].decimals /
+ *   PublicSession.token_decimals 로 서버가 내려준다. 6dp 를 하드코딩하면 non-6dp 토큰에서 금액이 틀린다.
+ *
+ * 정밀도 손실 방지를 위해 BigInt 연산만 사용한다 (Number 변환 금지 — CLAUDE.md 정책).
+ *   $1(6dp)   → "1000000"     $1(18dp) → "1000000000000000000"
+ */
+/**
+ * decimal 문자열 → atomic 문자열 (임의 decimals).
+ *
+ * @param decimal 소수 문자열(음수 불가, 소수 자리 ≤ decimals)
+ * @param decimals 토큰 decimals (예: 6, 18). payment_options[].decimals 사용.
+ * @throws {Error} 음수, decimals 초과 소수 자리, 형식 오류
+ * @example toAtomic('29.00', 6) // '29000000'   toAtomic('1.5', 18) // '1500000000000000000'
+ */
+declare function toAtomic(decimal: string, decimals: number): string;
+/**
+ * atomic 문자열 → 사람이 읽기 좋은 decimal 문자열 (임의 decimals).
+ * 최소 2자리 소수를 유지하되(예: '29.00'), decimals 만큼만 노출.
+ *
+ * @throws {Error} 정수 문자열이 아니면
+ * @example fromAtomic('29000000', 6) // '29.00'   fromAtomic('1500000000000000000', 18) // '1.50'
+ */
+declare function fromAtomic(atomic: string, decimals: number): string;
+/**
+ * decimal → atomic μUSDC (6dp). 하위호환 별칭 — 새 코드는 `toAtomic(decimal, decimals)` 권장
+ *   (BNB USDT=18dp 등 non-6dp 토큰은 이 헬퍼로 처리 불가).
+ * @example toAtomicUSDC('29.00') // '29000000'
+ */
+declare function toAtomicUSDC(decimal: string): string;
+/**
+ * atomic μUSDC(6dp) → decimal. 하위호환 별칭 — 새 코드는 `fromAtomic(atomic, decimals)` 권장.
+ * @example fromAtomicUSDC('29000000') // '29.00'
+ */
+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: 사람 표기 USD("29","0.5"). decimal 계산 불필요 — 체인/토큰 decimal 무관.
+ *   line_items: [{ name: 'Pro Plan', amount: '29', 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 CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type DepositAddress, 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, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, fromAtomic, fromAtomicUSDC, parseWebhookEvent, toAtomic, toAtomicUSDC, verifyWebhookSignature };