# npx でクイックスタート

> コマンドひとつでプロジェクトに Perly Pay を設定：支払いのルート、署名を検証する Webhook のルート、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`）に送信します。請求書を作成し、購入者を支払いへ案内します。
- **Webhook。** `/perly-pay/webhook` が生のボディで `Perly-Signature` を検証します。`invoice.fulfilled` で `grantAccess()` を呼びます — あなたが書く TODO はこれひとつ。
- **プラン。** 一回払いの販売とクレジットパックを、メインモジュール冒頭の `PLANS` に。プラン、そのクレジット、あなたのユーザー id は請求書のメタデータに入り、Webhook で戻ってきます。
- **キー。** `PERLY_PAY_SECRET_KEY` と `PERLY_PAY_WEBHOOK_SECRET` を `.env.local`（Next.js）または `.env` に、そのファイル自体を `.gitignore` に。git がすでにそのファイルを追跡している場合、init はキーを書かず、追跡を外す方法を案内します。

> **注:** init は既存のファイルや値を置き換えません。`--force` で置き換えます。

## Webhook を接続

Perly Pay が Webhook のアドレスに届く必要があります。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
```

ノートパソコンでは、トンネルが公開アドレスを用意します：`cloudflared tunnel --url http://localhost:3000`。詳しくは [Webhook](https://pay.perly.io/docs/webhooks.md) で。

## テストモードで 1 回支払う

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 の動作を確認** — Webhook が `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` のアドレスを登録し、そのシークレットを保存。 |
| `--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_…`）と本番の Webhook を作成します。
- アプリが動く場所にそれらを設定します。コードはそのまま。API の残りは [SDK](https://pay.perly.io/docs/sdks.md) で。