# بداية سريعة مع 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` (`/api/perly-pay/checkout` في Next.js). يفتح فاتورة ويوجّه المشتري لدفعها.
- **الويب هوك.** يتحقق `/perly-pay/webhook` من `Perly-Signature` على الجسم الخام. وعند `invoice.fulfilled` يستدعي `grantAccess()` — مهمة TODO الوحيدة التي تكتبها أنت.
- **الخطط.** مبيعات لمرة واحدة وباقات رصيد، في `PLANS` أعلى الوحدة الرئيسية. تنتقل الخطة ورصيدها ومعرّف المستخدم لديك في بيانات الفاتورة الوصفية وتعود في الويب هوك.
- **المفاتيح.** `PERLY_PAY_SECRET_KEY` و`PERLY_PAY_WEBHOOK_SECRET` في `.env.local` (Next.js) أو `.env`، والملف نفسه في `.gitignore`. إن كان git يتتبّع هذا الملف بالفعل، لا يكتب init المفتاح فيه ويشرح كيف تزيله من التتبّع.

> **ملاحظة:** لا يستبدل init أبدًا ملفًا أو قيمة موجودة. `--force` يستبدل.

## اربط الويب هوك

يجب أن يصل Perly Pay إلى عنوان الويب هوك. أضفه في 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`. المزيد في [الويب هوك](https://pay.perly.io/docs/webhooks.md).

## دفعة واحدة في وضع الاختبار

1. **شغّل التطبيق** — يقرأ Express وNode ملف `.env` عبر `node --env-file=.env` أو dotenv.
2. **افتح /perly-pay** — اضغط **Pay with crypto**. أنت في صفحة الدفع.
3. **Simulate payment** — تصبح الفاتورة مدفوعة، ثم منفّذة. انظر [وضع الاختبار](https://pay.perly.io/docs/test-mode.md).
4. **شاهد grantAccess يعمل** — يتلقى الويب هوك لديك `invoice.fulfilled`. الآن اكتب ما يمنحه.

## مع مساعد ذكاء اصطناعي

`--yes` لا يسأل شيئًا، لذا يشغّله Claude Code أو Cursor أو Codex نيابةً عنك. أعطه المفتاح وما تبيعه:

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

`--json` يطبع نتيجة يقرؤها المساعد.

## الخيارات

| العلَم | ما يفعله |
| --- | --- |
| `--yes`, `-y` | بلا أسئلة. لمساعدي الذكاء الاصطناعي والسكربتات. |
| `--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>` | ما تبيعه، بالدولار الأمريكي أو اليورو. `--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).