# Szybki start z npx

> Jedno polecenie konfiguruje Perly Pay w Twoim projekcie: trasę płatności, trasę webhooka z weryfikacją podpisu, przycisk Pay i Twój klucz testowy.

`npx perly-pay init` czyta Twój projekt, pisze kod pod jego framework i zostawia Cię jedno kliknięcie od płatności testowej. Konfiguruje tylko **tryb testowy**; produkcyjny włącza się w panelu.

## Uruchomienie

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

Wykrywa framework i menedżer pakietów, otwiera Dashboard → Developers i prosi o klucz testowy (`sk_test_…`). Klucz produkcyjny odrzuca.

## Co pisze

| Framework | Po czym go wykrywa | Pliki |
| --- | --- | --- |
| 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 | dowolny inny `package.json` | `lib/perly-pay.js`, `perly-pay.js` (`node:http`) |

TypeScript lub JavaScript, moduły ES lub CommonJS — jak w Twoim projekcie, i w `src/`, gdy kod tam jest. npm, pnpm, yarn, bun i Composer.

- **Płatność.** Przycisk wysyła formularz na `/perly-pay/checkout` (`/api/perly-pay/checkout` w Next.js). Ten otwiera fakturę i prowadzi kupującego do zapłaty.
- **Webhook.** `/perly-pay/webhook` weryfikuje `Perly-Signature` na surowym body. Na `invoice.fulfilled` wywołuje `grantAccess()` — jedyne TODO, które piszesz Ty.
- **Plany.** Sprzedaże jednorazowe i pakiety kredytów, w `PLANS` na początku głównego modułu. Plan, jego kredyty i Twoje id użytkownika jadą w metadanych faktury i wracają w webhooku.
- **Klucze.** `PERLY_PAY_SECRET_KEY` i `PERLY_PAY_WEBHOOK_SECRET` w `.env.local` (Next.js) lub `.env`, a sam plik — w `.gitignore`. Jeśli git już śledzi ten plik, init nie zapisuje w nim klucza i podpowiada, jak przestać go śledzić.

> **Uwaga:** init nigdy nie zastępuje istniejącego pliku ani wartości. `--force` zastępuje.

## Podłącz webhook

Perly Pay musi dotrzeć do adresu webhooka. Dodaj go w Dashboard → Developers → Webhooks dla `invoice.fulfilled` i wklej jego sekret `whsec_…` do `PERLY_PAY_WEBHOOK_SECRET`. Albo niech init zrobi oba kroki:

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

Na laptopie publiczny adres daje tunel: `cloudflared tunnel --url http://localhost:3000`. Więcej w [Webhookach](https://pay.perly.io/docs/webhooks.md).

## Jedna płatność w trybie testowym

1. **Uruchom aplikację** — Express i Node czytają `.env` przez `node --env-file=.env` lub dotenv.
2. **Otwórz /perly-pay** — Kliknij **Pay with crypto**. Jesteś na stronie płatności.
3. **Simulate payment** — Faktura staje się opłacona, potem zrealizowana. Zobacz [Tryb testowy](https://pay.perly.io/docs/test-mode.md).
4. **Zobacz, jak działa grantAccess** — Twój webhook dostaje `invoice.fulfilled`. Teraz napisz, co ma przyznawać.

## Z asystentem AI

`--yes` o nic nie pyta, więc Claude Code, Cursor czy Codex uruchomią go za Ciebie. Podaj klucz i to, co sprzedajesz:

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

`--json` drukuje wynik, który asystent odczyta.

## Opcje

| Flaga | Co robi |
| --- | --- |
| `--yes`, `-y` | Bez pytań. Dla asystentów AI i skryptów. |
| `--framework <name>` | `next`, `express`, `hono`, `laravel` lub `node`, gdy zgadnie źle. |
| `--key <sk_test_…>` | Twój klucz testowy. Domyślnie: `PERLY_PAY_SECRET_KEY`, albo pyta. |
| `--webhook-url <url>` | Rejestruje adres dla `invoice.fulfilled` i zapisuje jego sekret. |
| `--product <name>`, `--amount <cents>`, `--currency <code>` | Co sprzedajesz, w USD lub EUR. `--amount 4900` to $49.00. |
| `--install` | Dodatkowo instaluje SDK. W przeciwnym razie drukuje polecenie. |
| `--force` | Zastępuje istniejące pliki i wartości. |
| `--plugin`, `--mcp` | Drukuje, jak dodać wtyczkę Claude Code i serwer `perly-pay-mcp`. |
| `--dry-run` | Mówi, co by zrobił, nic nie zapisuje. |
| `--json` | Drukuje wynik jako JSON. |
| `--api <origin>`, `--dir <path>` | Inny Perly Pay (lokalny), inny katalog. |

## Tryb produkcyjny

- Podłącz **produkcyjne** klucze portfela w Dashboard → Wallets.
- Utwórz klucz produkcyjny (`sk_live_…`) i produkcyjny webhook.
- Ustaw je tam, gdzie działa aplikacja. Kod zostaje bez zmian. Reszta API — w [SDK](https://pay.perly.io/docs/sdks.md).