@bitpal/checkout 0.2.0 → 0.5.0

package/dist/index.cjs

@@ -0,0 +1,374 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BitPal: () => BitPal,
+  BitPalCheckoutClient: () => BitPalCheckoutClient,
+  BitPalError: () => BitPalError,
+  CHECKOUT_WEBHOOK_EVENTS: () => CHECKOUT_WEBHOOK_EVENTS,
+  PricesResource: () => PricesResource,
+  ProductsResource: () => ProductsResource,
+  WEBHOOK_HEADERS: () => WEBHOOK_HEADERS,
+  fromAtomicUSDC: () => fromAtomicUSDC,
+  parseWebhookEvent: () => parseWebhookEvent,
+  toAtomicUSDC: () => toAtomicUSDC,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/catalog.ts
+function toQuery(params) {
+  if (!params) return "";
+  const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+  if (entries.length === 0) return "";
+  const qs = new URLSearchParams(entries.map(([k, v]) => [k, String(v)]));
+  return `?${qs.toString()}`;
+}
+var ProductsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  /** POST /v1/checkout/products */
+  create(params) {
+    return this.request("POST", "/v1/checkout/products", params);
+  }
+  /** GET /v1/checkout/products */
+  list(params) {
+    return this.request("GET", `/v1/checkout/products${toQuery(params)}`);
+  }
+  /** GET /v1/checkout/products/:id */
+  retrieve(productId) {
+    return this.request("GET", `/v1/checkout/products/${encodeURIComponent(productId)}`);
+  }
+  /** PATCH /v1/checkout/products/:id */
+  update(productId, params) {
+    return this.request("PATCH", `/v1/checkout/products/${encodeURIComponent(productId)}`, params);
+  }
+};
+var PricesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  /** POST /v1/checkout/products/:id/prices */
+  create(productId, params) {
+    return this.request("POST", `/v1/checkout/products/${encodeURIComponent(productId)}/prices`, params);
+  }
+  /** GET /v1/checkout/products/:id/prices */
+  list(productId, params) {
+    return this.request("GET", `/v1/checkout/products/${encodeURIComponent(productId)}/prices${toQuery(params)}`);
+  }
+  /** GET /v1/checkout/prices/:id */
+  retrieve(priceId) {
+    return this.request("GET", `/v1/checkout/prices/${encodeURIComponent(priceId)}`);
+  }
+  /**
+   * PATCH /v1/checkout/prices/:id — nickname(표시 메타)만.
+   * 금액류 필드(amount_atomic 등)는 immutable — 서버가 PRICE_IMMUTABLE_FIELD로 거부한다.
+   * 가격 변경은 `prices.create()`로 새 price를 만들 것. "그만 팔기"는 해당 Price 를 쓰는
+   * Payment Link 를 inactive 로 한다(Price 자체에는 active/inactive 개념이 없다).
+   */
+  update(priceId, params) {
+    return this.request("PATCH", `/v1/checkout/prices/${encodeURIComponent(priceId)}`, params);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.bitpal.io";
+var DEFAULT_TIMEOUT = 3e4;
+var BitPalCheckoutClient = class {
+  /** 서버 메서드용 secret 키. 공개(buyer-facing) 메서드는 없이도 동작. */
+  apiKey;
+  baseUrl;
+  timeout;
+  /** PROD-LINK-3a-SDK: Product 카탈로그 관리 (server-side 전용) */
+  products;
+  /** PROD-LINK-3a-SDK: immutable Price 관리 — 가격 변경은 비활성화 + 새 price 생성 */
+  prices;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    const requester = (method, path, body) => this.request(method, path, body);
+    this.products = new ProductsResource(requester);
+    this.prices = new PricesResource(requester);
+  }
+  /* ─── 내부 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",
+          // 공개 메서드(session_token 기반)는 apiKey 없이 호출 가능 — 있을 때만 Authorization 첨부.
+          ...this.apiKey ? { 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할 결제 페이지
+   *
+   * // 멀티체인 허용 — 구매자가 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 사용(둘은 상호 배타).
+   */
+  async createSession(params) {
+    if (params.pay_chain && params.allowed_pay_chains && params.allowed_pay_chains.length > 0) {
+      throw new Error("[BitPal] pay_chain and allowed_pay_chains are mutually exclusive \u2014 use only one.");
+    }
+    const 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}` : ""}`
+    );
+  }
+  /* ─── 비수탁 결제 (deposit-address) ─── */
+  /**
+   * 공개 세션 조회 (`GET /v1/checkout/sessions/:id/public`) — 인증 불요.
+   *
+   * buyer-facing 결제 페이지가 표시/자산선택에 쓰는 서버 권위 뷰. `payment_options` 로
+   * 구매자 선택 가능한 chain×token 을 얻고, 발급 후에는 `deposit_address` 가 채워진다.
+   */
+  async getPublicSession(sessionId) {
+    return this.request(
+      "GET",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/public`
+    );
+  }
+  /**
+   * 주문별 비수탁 입금주소 발급 (`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); // 이 주소로 정확 금액 송금
+   * ```
+   */
+  async issueDepositAddress(sessionId, params) {
+    return this.request(
+      "POST",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/deposit-address`,
+      params
+    );
+  }
+  /**
+   * 경량 상태 폴링 (`GET /v1/checkout/sessions/:id/status`) — 인증 불요.
+   *
+   * status: awaiting_deposit → deposit_detected → paid_confirmed/swept. 확정/정산은 webhook 으로도
+   * 통지되므로, 서버 사이드 확정은 webhook 을 신뢰(폴링은 buyer UX 용).
+   */
+  async getStatus(sessionId) {
+    return this.request(
+      "GET",
+      `/v1/checkout/sessions/${encodeURIComponent(sessionId)}/status`
+    );
+  }
+  /* ─── 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.deposit_detected",
+  "checkout.session.paid",
+  "checkout.session.settled",
+  "checkout.session.expired",
+  "checkout.session.unresolved",
+  "checkout.refund.recorded"
+];
+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, opts) {
+  if (!payload || !signature || !secret) return false;
+  if (!signature.startsWith(SIGNATURE_PREFIX)) return false;
+  const timestamp = opts?.timestamp;
+  if (!timestamp) return false;
+  const parsedMs = Date.parse(timestamp);
+  if (!Number.isFinite(parsedMs)) return false;
+  if (new Date(parsedMs).toISOString() !== timestamp) return false;
+  const toleranceMs = (opts?.toleranceSec ?? 300) * 1e3;
+  if (Math.abs(Date.now() - parsedMs) > toleranceMs) return false;
+  const sigHex = signature.slice(SIGNATURE_PREFIX.length);
+  if (!/^[0-9a-f]{64}$/.test(sigHex)) return false;
+  try {
+    const crypto = await import("crypto");
+    const expectedHex = crypto.createHmac("sha256", secret).update(`${timestamp}.${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 = "0", 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);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BitPal,
+  BitPalCheckoutClient,
+  BitPalError,
+  CHECKOUT_WEBHOOK_EVENTS,
+  PricesResource,
+  ProductsResource,
+  WEBHOOK_HEADERS,
+  fromAtomicUSDC,
+  parseWebhookEvent,
+  toAtomicUSDC,
+  verifyWebhookSignature
+});