@team-oozoo/oozoo-pay 0.2.0

package/README.md

@@ -0,0 +1,139 @@
+# @team-oozoo/oozoo-pay
+
+OOZOO PAY JavaScript SDK for browser-based crypto payments.
+
+## Installation
+
+```bash
+npm install @team-oozoo/oozoo-pay
+# or
+pnpm add @team-oozoo/oozoo-pay
+# or
+yarn add @team-oozoo/oozoo-pay
+```
+
+## Quick Start
+
+### npm / ES Module
+
+```typescript
+import { loadOozooPay } from '@team-oozoo/oozoo-pay';
+
+const client = await loadOozooPay('pk_your_client_key');
+
+await client.pay({
+  price: 100,
+  unit: 'usd',
+  onCreateInvoice: async ({ price, chainId, tokenAddress, sender }) => {
+    const res = await fetch('/api/create-invoice', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ price, chainId, tokenAddress, sender }),
+    });
+    const data = await res.json();
+    return data.invoiceId;
+  },
+  successUrl: '/payment/success',
+  failUrl: '/payment/fail',
+});
+```
+
+### Script Tag (Standalone)
+
+```html
+<script src="https://unpkg.com/@team-oozoo/oozoo-pay/dist/standalone.global.js"></script>
+<script>
+  async function handlePay() {
+    const client = await OozooPay.load('pk_your_client_key');
+    await client.pay({
+      price: 100,
+      unit: 'usd',
+      onCreateInvoice: async (params) => {
+        const res = await fetch('/api/create-invoice', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(params),
+        });
+        const data = await res.json();
+        return data.invoiceId;
+      },
+      successUrl: '/payment/success',
+      failUrl: '/payment/fail',
+    });
+  }
+</script>
+```
+
+## API
+
+### `loadOozooPay(clientKey)`
+
+SDK 초기화 함수. `OozooPayClient` 인스턴스를 반환합니다.
+
+| Parameter   | Type     | Required | Description               |
+| ----------- | -------- | -------- | ------------------------- |
+| `clientKey` | `string` | Yes      | API Client Key (`pk_xxx`) |
+
+### `client.pay(options)`
+
+결제 창을 열고 사용자에게 결제를 받습니다.
+
+```typescript
+await client.pay({
+  price: 100,
+  unit: 'usd',
+  onCreateInvoice: async (params) => {
+    // 가맹점 서버에서 인보이스 생성 후 invoiceId 반환
+    return invoiceId;
+  },
+  successUrl: '/payment/success',
+  failUrl: '/payment/fail',
+});
+```
+
+| Option            | Type                          | Required | Description                                          |
+| ----------------- | ----------------------------- | -------- | ---------------------------------------------------- |
+| `price`           | `number`                      | Yes      | 결제 금액                                            |
+| `unit`            | `'usd'`                       | No       | 통화 단위 (기본: `'usd'`)                            |
+| `onCreateInvoice` | `(params) => Promise<string>` | Yes      | 인보이스 생성 콜백                                   |
+| `successUrl`      | `string`                      | Yes      | 결제 성공 시 리다이렉트 URL (`?invoiceId={id}` 추가) |
+| `failUrl`         | `string`                      | Yes      | 결제 실패/취소 시 리다이렉트 URL                     |
+
+#### `onCreateInvoice` Parameters
+
+| Field          | Type     | Description          |
+| -------------- | -------- | -------------------- |
+| `price`        | `number` | 결제 금액            |
+| `unit`         | `string` | 통화 단위            |
+| `chainId`      | `string` | 블록체인 네트워크 ID |
+| `tokenAddress` | `string` | 토큰 컨트랙트 주소   |
+| `sender`       | `string` | 결제자 지갑 주소     |
+
+#### `failUrl` Query Parameters
+
+| 상황        | Query Parameters                      | 예시                                    |
+| ----------- | ------------------------------------- | --------------------------------------- |
+| 사용자 취소 | `?code=CANCELLED`                     | `/fail?code=CANCELLED`                  |
+| 결제 에러   | `?code={ERROR_CODE}&message={메시지}` | `/fail?code=PAYMENT_FAILED&message=...` |
+
+### `client.transfer(options)`
+
+출금 창을 열고 사용자에게 출금합니다. `pay()`와 동일한 인터페이스이며, `onCreateInvoice` 파라미터에 `sender` 대신 `receiver`가 전달됩니다.
+
+```typescript
+await client.transfer({
+  price: 50,
+  unit: 'usd',
+  onCreateInvoice: async ({ price, chainId, tokenAddress, receiver }) => {
+    const res = await fetch('/api/create-transfer', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ price, chainId, tokenAddress, receiver }),
+    });
+    const data = await res.json();
+    return data.invoiceId;
+  },
+  successUrl: '/transfer/success',
+  failUrl: '/transfer/fail',
+});
+```