# npx로 빠른 시작

> 명령 하나로 프로젝트에 Perly Pay를 설정합니다: 결제 라우트, 서명을 검증하는 웹훅 라우트, Pay 버튼, 내 테스트 키.

`npx perly-pay init`은 프로젝트를 읽고, 프레임워크에 맞는 코드를 쓰고, 테스트 결제까지 클릭 한 번만 남겨 둡니다. **테스트 모드**만 설정하며, 라이브는 대시보드에서 켭니다.

## 실행

```bash
npx perly-pay init
```

프레임워크와 패키지 매니저를 찾고, Dashboard → Developers를 열어 테스트 키(`sk_test_…`)를 요청합니다. 라이브 키는 거부합니다.

## 쓰는 것

| 프레임워크 | 찾는 기준 | 파일 |
| --- | --- | --- |
| Next.js (App Router) | `next` | `lib/perly-pay.ts`, `app/api/perly-pay/checkout/route.ts`, `app/api/perly-pay/webhook/route.ts`, `components/PayButton.tsx`, `app/perly-pay/page.tsx` |
| Express | `express` | `lib/perly-pay.js`, `routes/perly-pay.js` |
| Hono | `hono` | `lib/perly-pay.ts`, `routes/perly-pay.ts` |
| Laravel | `artisan`, `laravel/framework` | `app/Http/Controllers/PerlyPayController.php`, `routes/perly-pay.php`, `config/perly-pay.php`, `resources/views/perly-pay/button.blade.php` |
| Node.js | 그 밖의 모든 `package.json` | `lib/perly-pay.js`, `perly-pay.js` (`node:http`) |

TypeScript든 JavaScript든, ES 모듈이든 CommonJS든 프로젝트를 따르고, 코드가 `src/`에 있으면 거기에. npm, pnpm, yarn, bun, Composer.

- **결제.** 버튼이 `/perly-pay/checkout`(Next.js에서는 `/api/perly-pay/checkout`)으로 폼을 보냅니다. 청구서를 열고 구매자를 결제로 안내합니다.
- **웹훅.** `/perly-pay/webhook`이 원본 본문으로 `Perly-Signature`를 검증합니다. `invoice.fulfilled`에서 `grantAccess()`를 부릅니다 — 직접 쓸 TODO는 이것 하나.
- **요금제.** 1회 판매와 크레딧 패키지, 메인 모듈 맨 위의 `PLANS`에. 요금제, 크레딧, 내 사용자 id가 청구서 메타데이터에 실려 웹훅으로 돌아옵니다.
- **키.** `PERLY_PAY_SECRET_KEY`와 `PERLY_PAY_WEBHOOK_SECRET`는 `.env.local`(Next.js) 또는 `.env`에, 그 파일은 `.gitignore`에. git이 이미 그 파일을 추적 중이면 init은 키를 쓰지 않고 추적을 해제하는 법을 알려 줍니다.

> **참고:** init은 이미 있는 파일이나 값을 절대 바꾸지 않습니다. `--force`는 바꿉니다.

## 웹훅 연결

Perly Pay가 웹훅 URL에 닿아야 합니다. Dashboard → Developers → Webhooks에서 `invoice.fulfilled`용으로 추가하고, 그 비밀 값 `whsec_…`를 `PERLY_PAY_WEBHOOK_SECRET`에 넣으세요. 또는 init이 두 단계를 모두 하게 하세요:

```bash
npx perly-pay init --webhook-url https://your-app.example/perly-pay/webhook
```

노트북에서는 터널이 공개 URL을 줍니다: `cloudflared tunnel --url http://localhost:3000`. 자세한 내용은 [웹훅](https://pay.perly.io/docs/webhooks.md)에서.

## 테스트 모드로 결제 한 번

1. **앱 실행** — Express와 Node는 `node --env-file=.env`나 dotenv로 `.env`를 읽습니다.
2. **/perly-pay 열기** — **Pay with crypto**를 누르세요. 결제 페이지가 열립니다.
3. **Simulate payment** — 청구서가 결제됨, 그다음 이행됨이 됩니다. [테스트 모드](https://pay.perly.io/docs/test-mode.md)를 보세요.
4. **grantAccess 동작 확인** — 웹훅이 `invoice.fulfilled`를 받습니다. 이제 무엇을 줄지 쓰세요.

## AI 어시스턴트와 함께

`--yes`는 아무것도 묻지 않으므로 Claude Code, Cursor, Codex가 대신 실행할 수 있습니다. 키와 판매할 것을 주세요:

```bash
npx perly-pay init --yes --key sk_test_… --product "Logo review" --amount 4900
```

`--json`은 어시스턴트가 읽을 수 있는 결과를 출력합니다.

## 옵션

| 플래그 | 기능 |
| --- | --- |
| `--yes`, `-y` | 질문 없이. AI 어시스턴트와 스크립트용. |
| `--framework <name>` | 추측이 틀렸을 때 `next`, `express`, `hono`, `laravel`, `node`. |
| `--key <sk_test_…>` | 내 테스트 키. 기본값: `PERLY_PAY_SECRET_KEY`, 없으면 물어봅니다. |
| `--webhook-url <url>` | `invoice.fulfilled`용 URL을 등록하고 그 비밀 값을 저장합니다. |
| `--product <name>`, `--amount <cents>`, `--currency <code>` | 판매하는 것, USD 또는 EUR로. `--amount 4900`은 $49.00. |
| `--install` | SDK도 설치합니다. 아니면 명령을 출력합니다. |
| `--force` | 이미 있는 파일과 값을 바꿉니다. |
| `--plugin`, `--mcp` | Claude Code 플러그인과 `perly-pay-mcp` 서버를 추가하는 법을 출력합니다. |
| `--dry-run` | 무엇을 할지 알려 주고, 아무것도 쓰지 않습니다. |
| `--json` | 결과를 JSON으로 출력합니다. |
| `--api <origin>`, `--dir <path>` | 다른 Perly Pay(로컬), 다른 폴더. |

## 라이브 모드

- Dashboard → Wallets에서 **라이브** 지갑 키를 연결하세요.
- 라이브 키(`sk_live_…`)와 라이브 웹훅을 만드세요.
- 앱이 도는 곳에 설정하세요. 코드는 그대로입니다. 나머지 API는 [SDK](https://pay.perly.io/docs/sdks.md)에서.