Eklentiler-Arası Mesajlaşma (messaging.send) ⏳ Yakında

POST {RESTOMENUM_BASE}/plugin-api/messaging/send
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "payload": {
    "to": { "customerId": "c_9f2…" },        // TİPLİ BİRLİK: { customerId } | { packetId } (tam biri).
                                              // ham telefon/e-posta 400 (rawPiiForbidden); telefonu SAĞLAYICI çözer.
    "channel": "whatsapp",                    // ops.: "whatsapp" | "sms" (yoksa sağlayıcı seçer)
    "text": "Rezervasyonunuz onaylandı 🎉",   // text VEYA template'ten en az biri (text ≤1600)
    "template": { "id": "rez-onay", "params": { "ad": "Ali" } },   // ops. (params ≤1KB)
    "idempotencyKey": "rez-42-onay",          // ZORUNLU ≤64 — çift mesaj koruması (aynı key farklı içerik → 409)
    "metadata": { "kaynak": "rezervasyon" }   // ops. ≤1KB, YALNIZ string/sayı/boolean değer (nested yasak); PII koyma
  }
}

// başarı — sağlayıcı isteği işledi (accepted = kuyruğa alındı; TESLİM DEĞİL)
{ "success": true, "data": {
    "requestId": "req_ab12…",            // idempotencyKey'den deterministik — durum eşleştirmede kullan
    "status": "accepted",                // "accepted" | "sent" | "failed"
    "providerMessageId": "wm_123",       // sağlayıcının kendi mesaj kimliği (varsa)
    "idempotentReplay": true             // yalnız tekrar çağrıda: önceki sonuç döndü, sağlayıcı ÇAĞRILMADI
} }

// sağlayıcının İŞ reddi (HTTP 200 — istek platformda başarıyla işlendi)
{ "success": true, "data": { "requestId": "req_…", "status": "failed",
    "error": { "code": "invalid_template", "message": "rez-onay bulunamadı" } } }

import { RestomenumClient } from '@restomenum/plugin-sdk';   // v1.5.0+

const r = await client.messaging.send({
  to: { customerId },
  text: 'Rezervasyonunuz onaylandı',
  idempotencyKey: `rez-${rezId}-onay`,   // iş-anlamlı + deterministik seç
});
// r.status: 'accepted' | 'sent' | 'failed'   (accepted ≠ delivered!)

// Sağlayıcı bağlı değilse: ApiError('plugin.messaging.noProvider', 424) → özelliği zarifçe gizle.
// Timeout/providerUnavailable: AYNI idempotencyKey ile retry et — başarı asla çift gönderilmez.

POST {actionUrl ?? webhookUrl}
Content-Type: application/json
X-Restomenum-Signature: t=<unixSec>,v1=<HMAC_SHA256(webhookSecret,"<t>.<rawBody>")>
X-Restomenum-Event: capability
X-Restomenum-Capability: messaging.send
X-Restomenum-Request: req_ab12…

{
  "type": "capability",                       // action/hook/webhook'tan bu alanla ayır
  "capability": "messaging.send",
  "v": 1,
  "environment": "sandbox",                   // "sandbox" | "production" — imzalı gövdede
  "tenantId": "kcK88…",
  "requestId": "req_ab12…",                   // AYNI requestId tekrar gelebilir → DEDUPE ZORUNLU
  "consumer": { "pluginId": "rezervasyon-x" },// isteği yapan tüketici (kota/metering için görünür)
  "occurredAt": 1780633662954,
  "payload": { "to": { "customerId": "c_9f2…" }, "channel": "whatsapp",
               "text": "…", "template": { … }, "metadata": { … } }
}

HTTP 200 (≤10 sn içinde)
{
  "status": "accepted",                 // "accepted" (kuyruğa alındı) | "sent" | "failed"
  "providerMessageId": "wm_123",        // ops. — kendi mesaj kimliğin
  "error": { "code": "…", "message": "…" }   // yalnız status:"failed" ise
}

import { verifyAndParseCapability, capabilityResponse } from '@restomenum/plugin-sdk';

// actionUrl handler'ında (webhook ile AYNI imza şeması):
const req = await verifyAndParseCapability(rawBody, headers['x-restomenum-signature'], {
  getSecret: (tenantId) => installStore.find(tenantId)?.webhookSecret,
});
if (!req) return res.status(401).json({ error: 'invalid_signature' });

// ZORUNLU DEDUPE: aynı requestId → mesajı YENİDEN GÖNDERME, önceki yanıtı dön.
const seen = sentStore.find(req.requestId);
if (seen) return res.json(capabilityResponse(seen.status, { providerMessageId: seen.providerMessageId }));

// telefonu TEK RESOLVER ile çöz (kaynağa göre dispatch: customerId→customers.get, packetId→packets.get):
import { resolveRecipientPhone } from '@restomenum/plugin-sdk';
const phone = await resolveRecipientPhone(client, req.payload.to);  // { customerId } | { packetId }
if (!phone) return res.json(capabilityResponse('failed', { error: { code: 'no_phone' } }));  // PII yetkisi/consent yok
// Scope: { customerId } → customers:read | { packetId } → orders:read + customers:read (+ tenant PII consent).
// … phone ile WhatsApp/SMS upstream'ine kuyrukla …
sentStore.save(req.requestId, { status: 'accepted', providerMessageId });
return res.json(capabilityResponse('accepted', { providerMessageId }));

// SAĞLAYICI (messaging:provide) — upstream DLR'ı raporla:
POST {RESTOMENUM_BASE}/plugin-api/messaging/status
Authorization: Bearer <apiKey>

{ "requestId": "req_ab12…",              // capability isteğinde aldığın kimlik
  "status": "delivered",                  // "sent" | "delivered" | "read" | "failed"
  "providerMessageId": "wm_123",          // ops.
  "error": { "code": "…", "message": "…" } }   // yalnız failed ile

// Yanıt: { "success": true, "data": { "recorded": true, "dispatched": true, "eventId": "evt_msgst_…" } }
// dispatched:false = rapor kayıtlı ama tüketiciye event gitmedi (kaldırılmış/abone değil/askıda) — hata değil.
// Yalnız KENDİ işlediğin istekleri raporlayabilirsin (başkasınınki → 404). Tekrar rapor güvenli
// (platform en-az-bir-kez teslim eder; tüketici zarf.id ile dedupe eder).

// TÜKETİCİ — manifest: events: ["messaging.message.status"] (+ events:subscribe scope)
// Webhook'una gelen zarf (yalnız SANA — istek sahibi kuruluma):
{ "id": "evt_msgst_5f1e9b2c…",            // deterministik: aynı raporun tekrarı aynı id (dedupe kolay)
  "type": "messaging.message.status",
  "version": "1", "environment": "sandbox", "tenantId": "…", "occurredAt": 1718200031000,
  "data": {
    "requestId": "req_ab12…",             // client.messaging.send dönüşündeki requestId ile eşle
    "status": "delivered",                 // sent → carrier'a verildi · delivered → ulaştı · read → okundu · failed → teslim edilemedi
    "providerMessageId": "wm_123",
    "error": { "code": "…" }               // yalnız failed ile
  } }