التحكم في الميزانية

تعيين حدود الإنفاق، وتتبع المدفوعات حسب النطاق، والحصول على ردود نداء قبل كل معاملة.

لماذا يهم التحكم في الميزانية

وكيل الذكاء الاصطناعي الذي يستدعي واجهات برمجية مدفوعة في حلقة متكررة يمكن أن يتراكم عليه تكاليف بسرعة. يتيح لك التحكم في الميزانية:

• تحديد سقف إجمالي للإنفاق لكل جلسة
• تعيين حدود لكل نطاق (مثلاً، بحد أقصى 100 sats/جلسة على api.weather.com)
• استقبال رد نداء قبل كل دفعة
• الحصول على تقرير إنفاق كامل في أي وقت

---

الميزانية الإجمالية

TypeScript

import { L402Client, BlinkWallet } from "l402-kit";

const client = new L402Client({
  wallet: new BlinkWallet(process.env.BLINK_API_KEY!, process.env.BLINK_WALLET_ID!),
  budgetSats: 500, // max 500 sats total this session
});

Python

from l402kit import L402Client
from l402kit.wallets import BlinkWallet

client = L402Client(
    wallet=BlinkWallet(os.environ["BLINK_API_KEY"], os.environ["BLINK_WALLET_ID"]),
    budget_sats=500,
)

عندما تتضمن استجابة 402 حقل priceSats وكانت ستتجاوز الميزانية المتبقية، يُطلق العميل BudgetExceededError قبل الدفع — لا يُصرف أي satoshi.

---

الميزانية لكل نطاق

TypeScript

const client = new L402Client({
  wallet,
  budgetSats: 2000,
  budgetPerDomain: {
    "api.weather.com": 100,
    "api.finance.com": 500,
  },
});

Python

client = L402Client(
    wallet=wallet,
    budget_sats=2000,
    budget_per_domain={
        "api.weather.com": 100,
        "api.finance.com": 500,
    },
)

يتم التحقق من حدود كل نطاق بشكل مستقل عن الحد الإجمالي — ويجب أن يجتاز كلاهما حتى تتم المعاملة.

---

ردود النداء

TypeScript

const client = new L402Client({
  wallet,
  budgetSats: 1000,
  onSpend: (sats, url) => {
    console.log(`✓ Paid ${sats} sats → ${url}`);
    // log to your telemetry, update a dashboard, etc.
  },
  onBudgetExceeded: (url, sats) => {
    console.warn(`✗ Blocked: ${sats} sats requested by ${url} — budget exhausted`);
    // alert, notify Slack, etc.
  },
});

Python

def on_spend(sats: int, url: str) -> None:
    print(f"✓ Paid {sats} sats → {url}")

def on_budget_exceeded(url: str, sats: int) -> None:
    print(f"✗ Blocked: {sats} sats requested by {url} — budget exhausted")

client = L402Client(
    wallet=wallet,
    budget_sats=1000,
    on_spend=on_spend,
    on_budget_exceeded=on_budget_exceeded,
)

يُستدعى onBudgetExceeded / on_budget_exceeded قبيل إطلاق BudgetExceededError مباشرةً — مفيد للتسجيل أو التنبيهات.

---

تقرير الإنفاق

TypeScript

const report = client.spendingReport();

if (report) {
  console.log(`Total spent: ${report.total} sats`);
  console.log(`Remaining:   ${report.remaining} sats`);
  console.log("By domain:", report.byDomain);
  // { "api.weather.com": 42, "api.finance.com": 105 }

  for (const tx of report.transactions) {
    console.log(`  ${tx.ts}  ${tx.sats} sats  ${tx.url}`);
  }
}

Python

report = client.spending_report()

if report:
    print(f"Total spent: {report.total} sats")
    print(f"Remaining:   {report.remaining} sats")
    print("By domain:", report.by_domain)
    # {"api.weather.com": 42, "api.finance.com": 105}

    for tx in report.transactions:
        print(f"  {tx['ts']}  {tx['sats']} sats  {tx['url']}")

تُرجع spendingReport() القيمة null / None عندما لا تكون هناك ميزانية مُهيأة.

---

معالجة BudgetExceededError

TypeScript

import { BudgetExceededError } from "l402-kit";

try {
  const res = await client.fetch("https://api.example.com/premium");
} catch (err) {
  if (err instanceof BudgetExceededError) {
    console.log(`Need ${err.required} sats, only ${err.remaining} remaining`);
    // gracefully degrade — return cached data, skip this step, etc.
  }
}

Python

from l402kit import BudgetExceededError

try:
    r = client.get("https://api.example.com/premium")
except BudgetExceededError as e:
    print(f"Need {e.required} sats, only {e.remaining} remaining")
    # gracefully degrade

---

ملاحظات حول التزامن

لا تشارك نسخة واحدة من L402Client عبر استدعاءات Promise.all المتزامنة عندما تكون حدود الميزانية مهمة.

يُفصل بين BudgetTracker.check() وrecord() بـawait (دفعة Lightning). قد تجتاز استدعاءان متزامنان لـclient.fetch() على نقاط نهاية مختلفة كلاهما فحص الميزانية قبل أن يسجّل أيٌّ منهما الإنفاق — مما يعني أن التكلفة الإجمالية قد تتجاوز مؤقتاً سقف ميزانيتك بمقدار دفعة واحدة.

النمط الآمن — الاستدعاءات المتسلسلة:

for (const url of urls) {
  const res = await client.fetch(url); // awaited one at a time
}

النمط الخطر — الاستدعاءات المتوازية:

// Both may pass budget.check() before either calls budget.record()
const results = await Promise.all(urls.map(url => client.fetch(url)));

الحل لأعباء العمل المتوازية: اضبط budgetSats بشكل متحفظ (مثلاً 80% من حدك الفعلي) لاستيعاب الإنفاق الزائد الناتج عن دفعة متزامنة واحدة. للتطبيق الصارم، عالج الاستدعاءات بشكل متسلسل.

---

مرجع الخيارات الكامل

الخيار	TypeScript	Python	الافتراضي	الوصف
الميزانية الإجمالية	budgetSats	budget_sats	غير محدودة	الحد الأقصى من sats للجلسة
لكل نطاق	budgetPerDomain	budget_per_domain	{}	خريطة من domain → max sats
خطاف الإنفاق	onSpend	on_spend	—	يُستدعى بعد كل دفعة
خطاف تجاوز الحد	onBudgetExceeded	on_budget_exceeded	—	يُستدعى قبل الإطلاق