🧰 UI vidjetlar: dasturchi uchun ma’lumotnoma

Bu sahifa vidjetning saqlanadigan formatini, uning funksiyalari sizning API ingiz bilan qanday gaplashishini va xatolik kontraktini tavsiflaydi. Foydalanuvchi yo‘riqnomasi — UI vidjetlar bo‘limida.

📦 Vidjet ta’rifi

.widget fayl va API dagi obyekt bir xil tuzilishga ega:

{
  "uuid": "…",
  "name": "Order status",
  "description": "Buyurtma holatini ko‘rsatadi",
  "category": "ecommerce",
  "tree": { "type": "Card", "children": [] },
  "schema": { "type": "object", "properties": {} },
  "defaultState": {},
  "examples": [{ "name": "Example 1", "state": {} }],
  "states": [],
  "functions": []
}

• category: booking | ecommerce | forms | analytics | other.
• tree — bitta ildiz tugun; JSX ko‘rinishi shu daraxtdan chop etiladi.
• schema — JSON Schema qism to‘plami: type, properties, items, required, enum, default, format, description.

🌲 Tugun daraxti

Har bir tugun — type maydoni bo‘lgan obyekt; bolalari children massivida:

{
  "type": "Card",
  "gap": 3,
  "children": [
    { "type": "Title", "value": "{{order.title}}", "size": "lg" },
    { "type": "Badge", "label": "{{order.status}}", "color": "info" },
    {
      "type": "Repeat",
      "each": "{{order.items}}",
      "as": "item",
      "children": [{ "type": "Text", "value": "{{item.name}}" }]
    }
  ]
}

• Bog‘lash — ikki jingalak qavs ichidagi yo‘l. Xossa faqat bitta bog‘lashdan iborat bo‘lsa, qiymat turi saqlanadi.
• Repeat — massiv bo‘yicha takrorlash (each, as); element tartibi <as>Index nomida.
• State — name bo‘yicha ko‘rinish qoidasiga bog‘lanadi.

⚙️ Funksiya obyektlari

{ "name": "confirm", "type": "call_api",
  "url": "https://api.example.com/book",
  "method": "POST",
  "headers": { "Authorization": "Bearer …" },
  "inputs": { "id": "{{order.id}}", "note": "{{note}}" },
  "additionalInputs": ["note"],
  "onSuccess": { "type": "set_variables", "variables": { "booked": true } },
  "onFailure": { "type": "set_variables", "variables": { "error": "…" } } }

Boshqa turlar: set_variables (variables), send_message (message, hidden), open_link (url), dismiss.

🔐 call_api qanday bajariladi

• Vidjet suhbatga yuborilayotganda call_api funksiyasining url, method, headers va inputs maydonlari olib tashlanadi va funksiya proksi orqali deb belgilanadi.
• Brauzer faqat funksiya nomini va kiritmalarni yuboradi; so‘rovni server sizning endpointingizga o‘zi bajaradi.
• Server tokenlarni xabar bilan saqlangan holat ustiga qabul qilingan kiritmalarni qo‘yib hisoblaydi.
• inputs — oq ro‘yxat: funksiyaning additionalInputs ida e’lon qilinmagan kalitlar tashlab yuboriladi.

🌐 Mehmon tomonidagi chaqiruv

POST /api/v1/widget/ui-widget/{widget_uuid}/functions/execute

{
  "message_uuid": "…",
  "function_name": "confirm",
  "inputs": { "note": "hi" },
  "tool_call_id": "call_1"
}

• Avtorizatsiya — chat vidjetining o‘z tokeni.
• message_uuid majburiy: u mehmonga shu vidjet ko‘rsatilganini isbotlaydi. Holat va sessiya server tomonda o‘qiladi, brauzerdan qabul qilinmaydi.
• tool_call_id — bitta xabar bir vidjetni ikki marta chizgan holat uchun.

🚨 Xatoliklar

{ "success": false, "error": { "code": "…", "message": "…" } }

• WIDGET_FUNCTION_NOT_CALLABLE — bu funksiyani mehmon chaqira olmaydi.
• WIDGET_INVALID_TOKEN, NOT_A_WIDGET_VISITOR — token muammosi.
• WIDGET_NOT_IN_MESSAGE — vidjet ko‘rsatilgan xabar topilmadi.
• WIDGET_FUNCTION_NOT_FOUND, WIDGET_FUNCTION_FAILED, WIDGET_FUNCTION_UNAVAILABLE.
• 429 — chastota chegarasi (daqiqasiga 60 so‘rov, IP bo‘yicha).
• 200 bilan ok: false — sizning API ingiz so‘rovni rad etgan.

📤 Sizning endpointingiz nima qaytarishi kerak

• JSON obyekt. waitForResponse yoqilgan bo‘lsa, javob vidjet ma’lumotiga qo‘shiladi va bog‘lashlar yangilanadi.
• Sxemadagi maydon nomlarini qaytaring yoki funksiya amalini API chaqirish + vidjet qilib, javobni moslashtirish dan foydalaning: { "orders": "data.items" }.
• Idempotentlik kaliti yo‘q — takroriy chaqiruvlarni o‘z tomoningizda himoyalang. Brauzer bir funksiyaning parallel chaqiruvini bloklaydi, lekin tarmoq qayta urinishlari mumkin.

🧾 Cheklovlar

• Daraxtda faqat ruxsat etilgan komponentlar bo‘lishi mumkin; boshqasi rad etiladi.
• Vidjetlar loyihaga bog‘langan: bir loyihaning vidjeti boshqa loyihada topilmaydi.
• Map komponenti va iframe orqali ishlaydigan client-funksiya hali qo‘llab-quvvatlanmaydi.