@bitpal/checkout 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -67,6 +67,17 @@ interface CreateSessionParams {
      * 예: ['eip155:84532', 'eip155:11155420', 'eip155:80002', 'eip155:421614']
      */
     allowed_pay_chains?: string[];
+    /**
+     * chain×token cell 허용 목록(**결제 수단** 표준 입력) — buyer 가 (체인, 토큰) 조합을 고른다.
+     * allowed_pay_chains(×단일 currency shorthand)보다 우선. 서로 다른 토큰을 섞을 때 사용.
+     * `chain` 은 short-name('base','tron','solana') 또는 CAIP-2 둘 다 허용(서버가 mode-relative 로 정규화).
+     * paymentLinks.allowed_assets 와 동일 형태(SDK 일관).
+     * 예: [{ chain: 'base', token: 'USDC' }, { chain: 'tron', token: 'USDT' }]
+     */
+    allowed_assets?: Array<{
+        chain: string;
+        token: string;
+    }>;
     /** 결제 자산 (예: USDC) */
     pay_asset?: string;
     /** 허용 오차 (%, 기본값: 2.00) */
@@ -677,6 +688,386 @@ declare function toAtomicUSDC(decimal: string): string;
  */
 declare function fromAtomicUSDC(atomic: string): string;
 
+/**
+ * x402 — 라우트 호출 1건당 과금하는 머천트 미들웨어.
+ *
+ * 머천트 코드는 "이 라우트는 $1" 만 선언한다. 402 조립, `X-PAYMENT` 파싱, verify → settle 순서,
+ * 에러 매핑, 재사용 차단은 전부 여기 안에 있다. 수수료는 BitPal이 계산해 402에 실어주므로
+ * 머천트는 **자기가 받고 싶은 총액(gross) 하나만** 넘긴다(체크아웃 `line_items[].amount` 와 동일 UX).
+ *
+ * 두 가지를 특히 조심해서 다룬다:
+ *
+ *  1. **"결제 1건 = 응답 1건" 은 미들웨어 책임이다.** BitPal `/settle` 의 멱등성은 "같은 nonce로 두 번
+ *     정산 요청해도 자금은 한 번만 움직인다" 만 보장한다. 같은 `X-PAYMENT` 를 100번 보내면 100번
+ *     성공 응답이 오므로, 그것만 믿으면 결제 1건으로 API를 무한 호출할 수 있다. 그래서 이미 리소스를
+ *     내준 authorization 을 로컬에 기록해 재사용을 막는다(`X402ReplayStore`).
+ *
+ *  2. **HTTP 200 은 정산 성공이 아니다.** 이미 종결된 결제를 다시 settle 하면 서버는 그 결과를 그대로
+ *     돌려준다 — `reverted` 여도 200 이다. 리소스는 `status === 'confirmed'` 일 때만 내준다.
+ */
+/** payer → resource server. base64(JSON) 결제 payload. */
+declare const X402_PAYMENT_HEADER = "x-payment";
+/** resource server → payer. base64(JSON) 정산 결과(txHash 포함). */
+declare const X402_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+interface X402FeeBreakdown {
+    netAmount: string;
+    feeAmount: string;
+    feeBps: number;
+    feeRecipient: string | null;
+}
+interface X402Accept {
+    scheme: 'exact';
+    network: string;
+    asset: string;
+    payTo: string;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    mimeType: string;
+    maxTimeoutSeconds: number;
+    /** payer 가 EIP-712 domain 을 그대로 만들 수 있는 값. */
+    extra: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+    /** BitPal 확장 — payer 가 merchant/fee 두 authorization 을 만들 수 있도록 서버가 확정한 분해. */
+    feeBreakdown: X402FeeBreakdown;
+}
+interface X402Requirements {
+    x402Version: 1;
+    accepts: X402Accept[];
+}
+interface Eip3009Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+    signature: {
+        v: number;
+        r: string;
+        s: string;
+    };
+}
+interface X402PaymentPayload {
+    x402Version: 1;
+    scheme: 'exact';
+    /** x402 wire 이름 — 'base' / 'base-sepolia'. */
+    network: string;
+    payload: {
+        merchant: Eip3009Authorization;
+        /** 서버가 계산한 feeAmount > 0 이면 필수. */
+        fee?: Eip3009Authorization;
+    };
+}
+/** `ok` = 이번 호출이 최초 점유 / `inflight` = 다른 요청이 처리 중 / `used` = 이미 리소스를 내줌. */
+type X402ClaimState = 'ok' | 'inflight' | 'used';
+/**
+ * authorization 재사용 차단 저장소.
+ *
+ * 기본 구현은 프로세스 메모리다 — 단일 인스턴스에선 충분하지만, 여러 인스턴스로 스케일 아웃하면
+ * 인스턴스마다 기억이 따로라 결제 1건으로 인스턴스 수만큼 호출할 수 있다. 다중 인스턴스 배포라면
+ * Redis/DB 기반 구현을 넘겨야 한다(키는 `network:from:nonce` 문자열 하나).
+ */
+interface X402ReplayStore {
+    claim(key: string, inflightTtlSeconds: number): X402ClaimState | Promise<X402ClaimState>;
+    /** 리소스를 내줬다 — 이 키는 영구 소진. */
+    commit(key: string): void | Promise<void>;
+    /** 정산이 안 끝났다 — 점유만 풀고 재시도를 허용(소진 처리 아님). */
+    release(key: string): void | Promise<void>;
+}
+/** 프로세스 메모리 기반 기본 store. */
+declare function createMemoryReplayStore(): X402ReplayStore;
+interface X402GateOptions {
+    /** 머천트가 이미 쓰고 있는 `bp_test_…` / `bp_live_…` 키. prefix 가 곧 네트워크(테스트/라이브)다. */
+    apiKey: string;
+    /** 정산 지갑. 콘솔에 등록한 payout 주소와 같은 값이어야 한다. */
+    payTo: string;
+    /** 호출 1건당 받을 총액(atomic). USDC 6dp 기준 $1 = `'1000000'`. 수수료는 여기서 차감된다. */
+    amount: string;
+    /** 생략 시 API 키 모드의 기본 자산(현재 Base / Base Sepolia). */
+    network?: string;
+    /** 기본 `'USDC'`. */
+    asset?: string;
+    description?: string;
+    mimeType?: string;
+    /** payer 가 서명을 만들어 재요청하기까지 주는 시간(초). 기본 300. */
+    maxTimeoutSeconds?: number;
+    baseUrl?: string;
+    /** BitPal API 호출 타임아웃(ms). settle 은 영수증까지 기다리므로 기본 60초. */
+    timeout?: number;
+    /** 다중 인스턴스 배포라면 공유 store 를 넘긴다. 기본은 프로세스 메모리. */
+    replayStore?: X402ReplayStore;
+}
+interface X402SettledPayment {
+    paymentId: string;
+    txHash: string | null;
+    /** 플랫폼 수수료 leg 의 tx. best-effort 라 merchant leg 가 확정돼도 null 일 수 있다. */
+    feeTxHash: string | null;
+    network: string;
+    /** payer 주소(merchant authorization 의 from). */
+    payer: string;
+    amount: string;
+    /** 이미 정산돼 있던 건을 그대로 돌려받았는지(감사·디버깅용). */
+    idempotent: boolean;
+}
+type X402GateResult = 
+/** 결제가 없거나 유효하지 않다 — 402 와 결제 조건을 그대로 내려준다. */
+{
+    kind: 'payment_required';
+    status: 402;
+    body: X402Requirements & {
+        error?: string;
+    };
+}
+/** 이 authorization 으로는 이미 리소스를 내줬다 — 재사용 거부. */
+ | {
+    kind: 'already_used';
+    status: 409;
+    body: {
+        error: string;
+        message: string;
+    };
+}
+/** 자금이 움직였는지 아직 확정 못 했다 — **같은** `X-PAYMENT` 로 재시도해야 한다(재서명 금지). */
+ | {
+    kind: 'unconfirmed';
+    status: 503;
+    body: {
+        error: string;
+        message: string;
+        paymentId?: string;
+    };
+}
+/**
+ * 정산 확정 — 리소스를 내주면 된다.
+ *
+ * 이 시점에 결제는 아직 **점유(inflight)** 상태다. 응답을 실제로 내보낸 뒤 `commit()` 을,
+ * 핸들러가 실패해 리소스를 못 줬으면 `release()` 를 불러야 한다. 둘 다 안 부르면 점유가
+ * TTL 까지 유지돼 그 사이 재시도가 503 으로 막힌다(이중 지급보다 안전한 방향).
+ */
+ | {
+    kind: 'settled';
+    status: 200;
+    payment: X402SettledPayment;
+    paymentResponseHeader: string;
+    commit: () => Promise<void>;
+    release: () => Promise<void>;
+};
+/**
+ * 프레임워크에 묶이지 않은 x402 게이트.
+ *
+ * Express 는 아래 `x402()` 어댑터를 쓰면 되고, Hono/Fastify/Next 등 다른 런타임은 이 클래스를 직접
+ * 감싸면 된다 — 헤더 하나와 resource URL 만 넘기면 "402 를 내려라 / 리소스를 내줘라" 를 돌려준다.
+ */
+declare class X402Gate {
+    private readonly opts;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly store;
+    private readonly maxTimeoutSeconds;
+    constructor(opts: X402GateOptions);
+    /** 이 리소스의 402 바디를 서버에서 받아온다(수수료 분해 포함). */
+    requirements(resource: string): Promise<X402Requirements>;
+    /**
+     * `X-PAYMENT` 헤더 1건을 처리한다. 헤더가 없거나 깨졌으면 402, 정산까지 끝나면 `settled`.
+     *
+     * 순서가 중요하다: **점유 → verify → settle → 소진 기록**. 점유를 verify 앞에 두어야 같은
+     * authorization 을 동시에 밀어 넣어도 한 요청만 리소스를 받는다.
+     */
+    collect(input: {
+        header?: string | null;
+        resource: string;
+    }): Promise<X402GateResult>;
+    private firstAccept;
+    private paymentRequired;
+    private request;
+}
+/** Express 요청에서 이 미들웨어가 실제로 읽는 필드만 추린 구조적 타입. */
+interface X402Request {
+    headers: Record<string, string | string[] | undefined>;
+    protocol?: string;
+    baseUrl?: string;
+    path?: string;
+    url?: string;
+    originalUrl?: string;
+    get?(name: string): string | undefined;
+    /** 정산 정보를 핸들러에서 쓸 수 있게 여기에 붙여준다. */
+    x402Payment?: X402SettledPayment;
+}
+/** Express 응답에서 이 미들웨어가 실제로 쓰는 메서드만 추린 구조적 타입. */
+interface X402Response {
+    status(code: number): X402Response;
+    json(body: unknown): unknown;
+    setHeader(name: string, value: string): unknown;
+    /** 응답이 실제로 나갔는지 보고 결제를 소진 처리한다. 없으면 즉시 소진 처리로 폴백. */
+    once?(event: string, listener: () => void): unknown;
+    statusCode?: number;
+    writableEnded?: boolean;
+}
+interface X402MiddlewareOptions extends X402GateOptions {
+    /**
+     * 이 결제가 묶일 리소스 URL. 기본값은 요청의 절대 URL(쿼리 제외).
+     * 결제는 이 값에 묶이므로 402 와 재요청에서 같은 값이 나와야 한다.
+     */
+    resource?: string | ((req: X402Request) => string);
+    /** 정산 확정 직후(핸들러 실행 전) 호출 — 로깅/사용량 집계용. */
+    onSettled?: (payment: X402SettledPayment, req: X402Request) => void | Promise<void>;
+}
+/**
+ * Express 라우트를 호출당 과금으로 감싼다.
+ *
+ * @example
+ * ```ts
+ * import { x402 } from '@bitpal/checkout';
+ *
+ * // 호출 1건당 $1.00 USDC
+ * app.get('/report', x402({
+ *   apiKey: process.env.BITPAL_API_KEY!,
+ *   payTo: '0xYourPayoutWallet',
+ *   network: 'base',
+ *   amount: '1000000',
+ * }), (req, res) => {
+ *   res.json({ report: '…' });
+ * });
+ * ```
+ */
+declare function x402(options: X402MiddlewareOptions): (req: X402Request, res: X402Response, next: (err?: unknown) => void) => Promise<void>;
+/**
+ * base64(JSON) 이 표준이지만, 평문 JSON 을 보내는 클라이언트도 받아준다.
+ *
+ * 인증 전에 임의의 외부 입력을 파싱하는 자리라 크기 상한과 형태 검증을 여기서 끝낸다 —
+ * 아래를 통과한 값만 replay key 와 BitPal API 바디로 들어간다. (프로토타입 오염은 이 payload 를
+ * 어디에도 merge 하지 않아 직접 경로는 없지만, `__proto__` 같은 키를 그대로 통과시키지 않는다.)
+ */
+declare function decodePaymentHeader(header: string): X402PaymentPayload;
+/** payer 헬퍼가 만든 payload 를 `X-PAYMENT` 헤더 값으로 인코딩한다. */
+declare function encodePaymentHeader(payload: X402PaymentPayload): string;
+
+/**
+ * x402-pay — payer 측 헬퍼. 402 응답을 받아 `X-PAYMENT` 헤더를 만들어 준다.
+ *
+ * BitPal 의 402 는 수수료를 forwarder 컨트랙트 없이 나누기 위해 authorization 을 두 개 요구한다
+ * (머천트 몫 + 플랫폼 수수료 몫). 순정 x402 클라이언트는 그 확장(`feeBreakdown`)을 모르므로,
+ * payer 쪽에서 그 차이를 흡수하는 게 이 파일의 존재 이유다. `feeBreakdown` 이 없는 평범한 402 도
+ * 그대로 처리한다 — 그 경우 authorization 하나만 만든다.
+ *
+ * 서명은 직접 하지 않는다. 지갑/키가 있는 쪽에서 `signTypedData` 하나만 넘기면 되고, 그래서 이
+ * SDK 는 암호 라이브러리 의존이 없다(viem / ethers / 브라우저 지갑 전부 몇 줄로 연결된다).
+ */
+
+/** EIP-3009 `TransferWithAuthorization` 의 EIP-712 타입 정의. */
+declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+interface Eip712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+interface X402TypedDataRequest {
+    domain: Eip712Domain;
+    types: typeof TRANSFER_WITH_AUTHORIZATION_TYPES;
+    primaryType: 'TransferWithAuthorization';
+    message: {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: string;
+    };
+}
+/**
+ * EIP-712 서명자. 65바이트 `0x…` 서명 문자열을 돌려주면 된다.
+ *
+ * @example viem
+ * ```ts
+ * const sign: X402Signer = (req) => walletClient.signTypedData({ account, ...req });
+ * ```
+ * @example ethers v6
+ * ```ts
+ * const sign: X402Signer = (req) => wallet.signTypedData(req.domain, req.types, req.message);
+ * ```
+ */
+type X402Signer = (request: X402TypedDataRequest) => Promise<string> | string;
+interface CreateX402PaymentOptions {
+    /** 402 응답 바디 전체, 또는 그 안의 `accepts[]` 한 칸. */
+    requirements: X402Requirements | X402Accept;
+    /** 지불자 주소. 서명자와 같은 주소여야 한다(서버가 recover 로 대조). */
+    from: string;
+    signTypedData: X402Signer;
+    /**
+     * 서명 유효시간(초). 기본은 402 의 `maxTimeoutSeconds`.
+     * BitPal 은 60초 미만·3600초 초과를 거부한다.
+     */
+    validForSeconds?: number;
+    /** 테스트에서 고정하기 위한 훅. 기본은 `Date.now()`. */
+    now?: () => number;
+    /** 테스트에서 고정하기 위한 훅. 기본은 CSPRNG 32바이트. */
+    randomNonce?: () => string;
+}
+interface X402PaymentResult {
+    /** 그대로 `X-PAYMENT` 헤더에 넣으면 되는 base64 문자열. */
+    header: string;
+    payload: X402PaymentPayload;
+    /** 지갑에서 실제로 빠져나가는 총액(머천트 몫 + 수수료 몫). */
+    totalAmount: string;
+}
+/**
+ * 402 응답 → 서명된 `X-PAYMENT` 헤더.
+ *
+ * 수수료가 있으면 서명 프롬프트가 두 번 뜬다(머천트 몫 1건, 수수료 몫 1건). 두 authorization 은
+ * 같은 유효창을 쓴다 — 수수료 쪽이 먼저 만료되면 머천트 정산 뒤 수수료만 못 걷히기 때문에
+ * 서버가 "수수료 창이 결제 창을 덮을 것"을 요구한다.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch(url);
+ * if (res.status === 402) {
+ *   const { header } = await createX402Payment({
+ *     requirements: await res.json(),
+ *     from: account.address,
+ *     signTypedData: (req) => walletClient.signTypedData({ account, ...req }),
+ *   });
+ *   const paid = await fetch(url, { headers: { 'X-PAYMENT': header } });
+ * }
+ * ```
+ */
+declare function createX402Payment(options: CreateX402PaymentOptions): Promise<X402PaymentResult>;
+/**
+ * 서명 → `{v, r, s}`. BitPal API 가 요구하는 분해 형태.
+ *
+ * 65바이트(r‖s‖v)와 64바이트 EIP-2098 compact(r‖yParityAndS) 둘 다 받는다 — viem 의
+ * `signTypedData` 는 65바이트를 주지만 일부 지갑·라이브러리는 compact 를 돌려준다.
+ */
+declare function splitSignature(signature: string): {
+    v: number;
+    r: string;
+    s: string;
+};
+
 /**
  * @bitpal/checkout — BitPal Checkout SDK
  *
@@ -705,4 +1096,4 @@ declare class BitPal {
     constructor(config: BitPalConfig | string);
 }
 
-export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type 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 };
+export { type ApiResponse, BitPal, BitPalCheckoutClient, type BitPalConfig, BitPalError, CHECKOUT_WEBHOOK_EVENTS, type CheckoutLineItemInput, type CheckoutPaymentLink, type CheckoutPrice, type CheckoutProduct, type CheckoutSession, type CheckoutWebhookEvent, type CreatePaymentLinkParams, type CreatePriceParams, type CreateProductParams, type CreateSessionParams, type CreateX402PaymentOptions, type DepositAddress, type Eip3009Authorization, type Eip712Domain, type FeePreview, type IdempotencyOptions, type IssueDepositAddressParams, type LineItem, type ListPaymentLinksParams, type ListPricesParams, type ListProductsParams, type ListResponse, PaymentLinksResource, type PaymentOption, type PriceLineItem, PricesResource, ProductsResource, type PublicSession, type SessionStatus, TRANSFER_WITH_AUTHORIZATION_TYPES, type UpdatePaymentLinkParams, type UpdatePriceParams, type UpdateProductParams, WEBHOOK_HEADERS, type WebhookPayload, type X402Accept, type X402ClaimState, type X402FeeBreakdown, X402Gate, type X402GateOptions, type X402GateResult, type X402MiddlewareOptions, type X402PaymentPayload, type X402PaymentResult, type X402ReplayStore, type X402Request, type X402Requirements, type X402Response, type X402SettledPayment, type X402Signer, type X402TypedDataRequest, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, createMemoryReplayStore, createX402Payment, decodePaymentHeader, encodePaymentHeader, fromAtomic, fromAtomicUSDC, parseWebhookEvent, splitSignature, toAtomic, toAtomicUSDC, verifyWebhookSignature, x402 };