open-index/open-npm huggingface dataset:
npm package: @k-stable/sdk
Description: 쇼핑몰 FE에서 Wallet 결제창을 호출하기 위한 SDK입니다.
Latest version: 0.6.0

# @k-stable/sdk

쇼핑몰 FE에서 Wallet 결제창을 호출하기 위한 SDK입니다.

- 쇼핑몰 도입 가이드: [SHOPPING_MALL_INTEGRATION_GUIDE.md](./SHOPPING_MALL_INTEGRATION_GUIDE.md)

## 설치

```bash
npm i @k-stable/sdk
```

## 핵심 API (Toss-style)

```ts
import { loadKStablePay, ANONYMOUS } from '@k-stable/sdk';

const kStable = await loadKStablePay('YOUR_CLIENT_KEY');

const widget = kStable.wallet(ANONYMOUS); // 회원이면 customer UUID

widget.setInfo({
  customerName: '홍길동',
  customerPhone: '01012345678',
  productName: '멤버십 구독권',
  amount: 12000,
  checkoutExpiresAt: '2026-03-19T12:30:00.000Z',
});

widget.renderWallet('#wallet-widget');

widget.requestPayment({
  orderId: 'order-001',
  customerId: 'uuid-...',
  customerName: '홍길동',
  customerPhone: '01012345678',
  productName: '멤버십 구독권',
  amount: 12000,
  successUrl: 'https://shop.example.com/pay/success',
  failUrl: 'https://shop.example.com/pay/fail',
  checkoutExpiresAt: '2026-03-19T12:30:00.000Z',
});
```

- 회원 결제: `customerKey = 회원 UUID`
- 비회원 결제: `customerKey = ANONYMOUS`
- SDK 초기화는 `clientKey`로만 수행합니다.

고급 옵션이 필요한 경우:

```ts
await loadKStablePay('YOUR_CLIENT_KEY', {
  checkoutOrigin: 'https://wallet.example.com',
  checkoutPath: '/checkout',
  appDeepLinkBaseUrl: 'kwallet://checkout',
  defaultOpenStrategy: 'APP_FIRST',
  fallbackTimeoutMs: 1200,
});
```

## 결제 전략

- `APP_FIRST`
  - Wallet 앱 열기 시도
  - 앱 미설치/취소/실패 시 웹 checkout으로 fallback
- `WEB_ONLY`
  - 바로 웹 checkout 이동

`checkoutExpiresAt`이 지난 상태에서 결제 요청 시 SDK가 `SESSION_EXPIRED`로 `failUrl` 이동 처리합니다.

## 결과 파싱

```ts
import { initWalletSdk, assertSuccessResult } from '@k-stable/sdk';

const sdk = initWalletSdk({
  checkoutOrigin: 'https://wallet.example.com',
  merchantId: 'mrc_demo_001',
});

const result = sdk.parseRedirectResult(window.location.href);
if (result.type === 'SUCCESS') {
  assertSuccessResult(result, { orderId: 'order-001', amount: 12000 });
}
```

## Legacy API (호환)

기존 `initWalletSdk().requestPaymentRedirect(...)`도 계속 사용 가능합니다.

## UI preview (local)

```bash
cd /Users/moonyaeyoon/k-stable-pay/wallet/open-sdk
npm run build
python3 -m http.server 5500
```

- `http://localhost:5500/examples/preview/merchant.html`