# npx ile hızlı başlangıç

> Tek komut Perly Pay'i projende kurar: ödeme rotası, imza doğrulamalı webhook rotası, Pay butonu ve test anahtarın.

`npx perly-pay init` projeni okur, kodu framework'üne göre yazar ve seni bir test ödemesine tek tık uzaklıkta bırakır. Yalnızca **test modunu** kurar; canlı mod panelden açılır.

## Çalıştırma

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

Framework'ü ve paket yöneticisini bulur, Dashboard → Developers'ı açar ve test anahtarını (`sk_test_…`) ister. Canlı anahtarı reddeder.

## Ne yazar

| Framework | Neye bakarak bulur | Dosyalar |
| --- | --- | --- |
| 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 | başka herhangi bir `package.json` | `lib/perly-pay.js`, `perly-pay.js` (`node:http`) |

TypeScript ya da JavaScript, ES modülleri ya da CommonJS — projendeki gibi; kod oradaysa `src/` içinde. npm, pnpm, yarn, bun ve Composer.

- **Ödeme.** Buton formu `/perly-pay/checkout` adresine gönderir (Next.js'te `/api/perly-pay/checkout`). Bu rota bir fatura açar ve alıcıyı ödemeye yönlendirir.
- **Webhook.** `/perly-pay/webhook`, `Perly-Signature`'ı ham gövde üzerinde doğrular. `invoice.fulfilled` geldiğinde `grantAccess()` çağırır — senin yazacağın tek TODO.
- **Planlar.** Tek seferlik satışlar ve kredi paketleri, ana modülün başındaki `PLANS` içinde. Plan, kredileri ve kullanıcı id'n fatura metadata'sında gider ve webhook'ta geri gelir.
- **Anahtarlar.** `PERLY_PAY_SECRET_KEY` ve `PERLY_PAY_WEBHOOK_SECRET`, `.env.local` (Next.js) ya da `.env` içinde; dosyanın kendisi `.gitignore`'da. git bu dosyayı zaten izliyorsa init anahtarı oraya yazmaz ve izlemeden nasıl çıkarılacağını söyler.

> **Not:** init var olan bir dosyayı ya da değeri asla değiştirmez. `--force` değiştirir.

## Webhook'u bağla

Perly Pay'in webhook adresine ulaşabilmesi gerekir. Adresi Dashboard → Developers → Webhooks'ta `invoice.fulfilled` için ekle ve `whsec_…` secret'ını `PERLY_PAY_WEBHOOK_SECRET` içine yapıştır. Ya da iki adımı da init yapsın:

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

Dizüstü bilgisayarda herkese açık adresi bir tünel verir: `cloudflared tunnel --url http://localhost:3000`. Fazlası [Webhook'lar](https://pay.perly.io/docs/webhooks.md) sayfasında.

## Test modunda bir ödeme

1. **Uygulamayı başlat** — Express ve Node, `.env`'i `node --env-file=.env` ya da dotenv ile okur.
2. **/perly-pay'i aç** — **Pay with crypto**'ya bas. Ödeme sayfasındasın.
3. **Simulate payment** — Fatura önce ödendi, sonra teslim edildi olur. Bkz. [Test modu](https://pay.perly.io/docs/test-mode.md).
4. **grantAccess'in çalıştığını gör** — Webhook'un `invoice.fulfilled` alır. Şimdi ne vereceğini yaz.

## Bir AI asistanıyla

`--yes` hiçbir şey sormaz, bu yüzden Claude Code, Cursor ya da Codex onu senin yerine çalıştırabilir. Anahtarı ve ne sattığını ver:

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

`--json`, asistanın okuyabileceği bir sonuç yazdırır.

## Seçenekler

| Bayrak | Ne yapar |
| --- | --- |
| `--yes`, `-y` | Soru sormaz. AI asistanları ve scriptler için. |
| `--framework <name>` | Yanlış tahmin edildiğinde `next`, `express`, `hono`, `laravel` ya da `node`. |
| `--key <sk_test_…>` | Test anahtarın. Varsayılan: `PERLY_PAY_SECRET_KEY`, yoksa sorar. |
| `--webhook-url <url>` | `invoice.fulfilled` için adresi kaydeder ve secret'ını saklar. |
| `--product <name>`, `--amount <cents>`, `--currency <code>` | Ne sattığın, USD ya da EUR olarak. `--amount 4900`, $49.00 demek. |
| `--install` | SDK'yı da kurar. Yoksa komutu yazdırır. |
| `--force` | Var olan dosyaları ve değerleri değiştirir. |
| `--plugin`, `--mcp` | Claude Code eklentisinin ve `perly-pay-mcp` sunucusunun nasıl ekleneceğini yazdırır. |
| `--dry-run` | Ne yapacağını söyler, hiçbir şey yazmaz. |
| `--json` | Sonucu JSON olarak yazdırır. |
| `--api <origin>`, `--dir <path>` | Başka bir Perly Pay (yerel), başka bir klasör. |

## Canlı mod

- **Canlı** cüzdan anahtarlarını Dashboard → Wallets'ta bağla.
- Canlı bir anahtar (`sk_live_…`) ve canlı bir webhook oluştur.
- Bunları uygulamanın çalıştığı yerde ayarla. Kod olduğu gibi kalır. API'nin geri kalanı [SDK'lar](https://pay.perly.io/docs/sdks.md) sayfasında.