# وصفة: بوت Telegram

> بِع أوامر البوت، أو دورًا، أو مجموعة خاصة. يحصل كل مستخدم على فاتورته؛ ويفتح ويب هوك موقّع الوصول.

البوت لا يرى الأموال. عند `/buy` يرسل للمستخدم رابط فاتورته الخاصة؛ ويسمع خادمك `invoice.fulfilled` فيفتح الوصول. كل أمر مدفوع يسأل Perly Pay، لذا لا يضيع شيء بعد إعادة التشغيل. وDiscord بالطريقة نفسها، عبر دور.

> **ملاحظة:** مع مساعد: تنفّذ هذه الوصفة في مشروعك مهارة `sell-bot-access` من إضافة Perly Pay. المثال القابل للتشغيل هو `examples/telegram-bot` (MIT) في مستودع الإضافة.

## كيف يعمل

1. **المنتج والسعر** — لمرة واحدة أو مدى الحياة — «للأبد»، ولمدة — للتصاريح، واشتراك — لعضوية تتجدد بالفاتورة.
2. **عميل لكل مستخدم في الدردشة** — `external_id: "tg:<user id>"`. اطلب البريد للاشتراكات فقط: إليه تذهب التجديدات.
3. **/buy** — فاتورة مع معرّف الدردشة في `metadata`، تُرسل بزر. فاتورة واحدة لكل مستخدم في اليوم — بفضل مفتاح عدم التكرار.
4. **افتح الوصول** — عند `invoice.fulfilled` خذ معرّف الدردشة من `metadata` وأجب: رسالة، أو دعوة لمرة واحدة، أو دور.
5. **الأوامر المدفوعة** — `entitlements.check({ customer_external_id: "tg:<id>", product })`.

**/buy**

```js
const invoice = await pay.invoices.create(
  { line_items: [{ price: PRICE }], customer: customer.id, metadata: { chat_id: String(chatId) } },
  { idempotencyKey: `buy-${userId}-${today}` },
);
await tg("sendMessage", { chat_id: chatId, text: "Pay:", reply_markup: { inline_keyboard: [[{ text: "Pay", url: invoice.url }]] } });
```

## شغّل المثال

1. **ثبّت** — `npm install` في `examples/telegram-bot` (Node 20.12+).
2. **المفتاح** — انسخ `.env.example` إلى `.env` واكتب مفتاح الاختبار (`sk_test_…`) في `PERLY_PAY_SECRET_KEY`.
3. **حضّر** — `npm run setup` ينشئ المنتج والسعر بمفتاحك ويطبع معرّفاتهما لـ `.env`.
4. **شغّل** — `npm start` (أو `npm run dev`)، كما يقول ملف README الخاص به.
5. **ادفع بلا محفظة** — اكتب للبوت `/buy`، وافتح Pay واضغط **Simulate payment**: سيقول البوت «Payment confirmed»، وسيجيب `/secret`.

## مزالق

- رابط دفع مشترك واحد للجميع: لا يُعرف من دفع. فاتورة لكل مستخدم، مع معرّف الدردشة.
- فتح الوصول حين يضغط المستخدم «دفعت». لا يفتحه إلا الويب هوك أو `entitlements.check`.
- الوصول في ذاكرة البوت. بعد إعادة التشغيل يختفي؛ اسأل Perly Pay.