Eklentiler-Arası Yetenekler (Capability) ⏳ Yakında

Model — tüketici, sağlayıcı, binding

İki rol var: tüketici (yeteneği çağırır — capability:<id>:consume) ve sağlayıcı (yeteneği sağlar — capability:<id>:provide). Eklentiler birbirini asla doğrudan çağırmaz; tek aracı platform runtime'ıdır. Tenant her yetenek için bir sağlayıcı bağlar (tek aday varsa otomatik; panelden değiştirilebilir) — tüketici hangi sağlayıcının bağlı olduğunu bilmez.

Tüketici eklenti          Restomenum (platform)              Sağlayıcı eklenti
(rezervasyon, POS…)                                            (WhatsApp / e-fatura…)
     │                              │                                │
     │ POST /plugin-api/            │                                │
     │  capabilities/{cap}/invoke   │                                │
     │ Bearer <apiKey>              │                                │
     │─────────────────────────────►│ scope + ham-PII reddi          │
     │                              │ + kota + idempotency ledger    │
     │                              │ tenant'ın BAĞLADIĞI sağlayıcı  │
     │                              │ (binding / tek-adayda auto-bind)│
     │                              │                                │
     │                              │ imzalı POST type:"capability"  │
     │                              │───────────────────────────────►│ imza doğrula (webhook ile aynı)
     │                              │                                │ requestId DEDUPE (zorunlu)
     │                              │  { status, providerMessageId } │ opak referansı çöz + işi yap
     │                              │◄───────────────────────────────│ (customers/users:read + consent)
     │  { requestId, status,        │                                │
     │    providerMessageId }       │                                │
     │◄─────────────────────────────│                                │
     │                              │  (async) POST .../status       │ nihai sonuç (DLR / GİB)
     │  event: <cap>.status ◄───────│◄───────────────────────────────│

Kayıtlı yetenekler

Platform-tanımlı yetenekler (her biri kendi payload/durum sözleşmesine sahip):

Tüketici — bir yeteneği çağır

Jenerik uç: POST /plugin-api/capabilities/{capabilityId}/invoke. SDK ile client.capabilities.invoke('<id>', payload) — payload tipi id'den türer, idempotencyKey her istekte zorunlu.

POST {RESTOMENUM_BASE}/plugin-api/capabilities/{capabilityId}/invoke
Authorization: Bearer <apiKey>
Content-Type: application/json

{ "payload": {
    "to": { "customerId": "c_…" },      // capability-özel; ham PII (telefon/VKN) YASAK
    "idempotencyKey": "iş-anlamlı-key",  // ZORUNLU (≤64) — çift işlem koruması
    "…": "…"                              // messaging: text/template · invoice: amount/items · notify: title/body
} }

{ "success": true, "data": {
    "requestId": "req_…",                 // idempotencyKey'den deterministik
    "status": "accepted",                 // capability-özel senkron durum (aşağıdaki tablo)
    "providerMessageId": "…",             // sağlayıcının kimliği (varsa)
    "idempotentReplay": false             // true → önceki başarılı isteğin tekrarı (sağlayıcı YENİDEN çağrılmadı)
} }

Sağlayıcı olma rehberi

Sağlayıcı eklenti, provides ettiği yetenek için platformdan imzalı capability isteği alır (actionUrl'üne, yoksa webhookUrl'üne). İmza şeması webhook ile birebir aynıdır.

POST <sağlayıcının actionUrl'ü (yoksa webhookUrl)>
X-Restomenum-Signature: t=<unixSec>,v1=HMAC_SHA256(webhookSecret,"<t>.<rawBody>")
X-Restomenum-Event: capability
X-Restomenum-Capability: invoice.issue
X-Restomenum-Request: req_…

{ "type": "capability", "capability": "invoice.issue", "v": 1,
  "environment": "sandbox",               // "sandbox" | "production" — imzalı gövdede
  "tenantId": "…", "requestId": "req_…",
  "consumer": { "pluginId": "…" },        // isteği yapan tüketici (kota/metering)
  "occurredAt": 0,
  "payload": { … } }                       // platform allowlist'inden geçmiş (ham PII yok)

Adımlar (SDK ile):

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

// 1) İMZA + ŞEKİL doğrula (webhook ile AYNI HMAC şeması). null → 401 dön.
const req = await verifyAndParseCapability<InvoiceIssuePayload>(rawBody, sigHeader, {
  getSecret: (tenantId) => installStore.find(tenantId)?.webhookSecret,
});
if (!req) return res.status(401).json({ error: 'invalid_signature' });

// 2) requestId DEDUPE (ZORUNLU sözleşme — review kriteri): aynı requestId tekrar gelirse işi YENİDEN
//    YAPMA (mesaj/fatura), önceki providerMessageId ile AYNI yanıtı dön.
const prior = await store.find(req.requestId);
if (prior) return res.json(capabilityResponse(prior.status, { providerMessageId: prior.providerMessageId }));

// 3) İşi yap: to.customerId OPAK → gerekirse client.customers.get(customerId) (customers:read + PII consent).
const providerMessageId = await issueInvoiceAtGib(req.payload);
await store.save(req.requestId, { status: 'issued', providerMessageId });

// 4) Senkron yanıt — status capability'nin responseStatuses whitelist'inden olmalı (invoice: accepted|issued|failed).
res.json(capabilityResponse<InvoiceIssueStatus>('issued', { providerMessageId }));

Nihai sonucu (DLR / GİB durumu) dakikalar sonra asenkron raporla:

// invoice.issue / messaging.send ASYNC sonucu (dakikalar sonra): nihai durumu raporla →
// platform YALNIZ istek sahibi tüketiciye hedefli <cap>.status event'i teslim eder (broadcast yok).
await client.capabilities.reportStatus('invoice.issue', {
  requestId: req.requestId,        // capability isteğinde aldığın req_… (kendi fatura no'n DEĞİL)
  status: 'paid',                  // issued→paid ileri; void/failed terminal (MONOTON)
  providerMessageId,
});
// notify.staff fire-and-forget'tir (asenkron durum YOK).

Hata kodları

Tam kod plugin.<errorPrefix>.<suffix>; <pfx> = capability id'nin İLK segmenti: messaging.send → plugin.messaging, notify.staff → plugin.notify, invoice.issue → plugin.invoice (ör. notify.staff için plugin.notify.noProvider, plugin.notify.staff.* DEĞİL). SDK'da CAPABILITY_ERRORS + capabilityErrorCode('<id>', suffix) tip-güvenli guard sağlar.

Kota: capability çağrıları ortak cap:<id> kovasını kullanır (varsayılan 60/dk/install; dev-store projesinde 5/dk) — bkz. Limitler.

Yetenek sayfaları

• Mesajlaşma (messaging.send) — müşteriye WhatsApp/SMS; DLR durum event'i.
• Personel Bildirimi (notify.staff) — role/userId'ye bildirim; fire-and-forget.
• Fatura Kesme (invoice.issue) — e-fatura; asenkron invoice.status.
• Scope Referansı — türetilmiş capability:* scope'ları + PII.
• Hata Sözlüğü · Limitler