Fatura Kesme (invoice.issue) ⏳ Yakında

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

// TÜKETİCİ (scope: capability:invoice.issue:consume) — jenerik capability yolu.
// Sonuç tipi (InvoiceIssueResult) capability id'den OTOMATİK türer; elle <> tip argümanı GEREKMEZ.
const r = await client.capabilities.invoke('invoice.issue', {
  to: { customerId: 'cust_123' },        // OPSİYONEL opak referans; sağlayıcı customers:read ile çözer
  amount: { total: 12345, currency: 'TRY' },  // total KURUŞ (integer) → 12345 = ₺123,45. ondalık YOK
  items: [                               // opsiyonel kalemler (unitPrice de KURUŞ)
    { description: 'Adana Kebap', quantity: 2, unitPrice: 4500 },
    { description: 'Ayran', quantity: 3, unitPrice: 1115 },
  ],
  reference: 'packet_789',               // opsiyonel dış referans (paket/sipariş no)
  idempotencyKey: `invoice-${packetId}`,  // ZORUNLU — çift fatura koruması (mali/yasal risk)
});
// r = { requestId, status: 'accepted'|'issued'|'failed', providerMessageId?, idempotentReplay? }
// 'accepted' = kesim kuyruğa alındı (sonuç invoice.status event'iyle gelir); 'issued' = anında kesildi.
// Sağlayıcı bağlı değilse ApiError('plugin.invoice.noProvider', 424) → özelliği gizle.

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

// SAĞLAYICI (scope: capability:invoice.issue:provide) — actionUrl'e gelen imzalı type:"capability" POST:
const req = await verifyAndParseCapability<InvoiceIssuePayload>(rawBody, headers['x-restomenum-signature'], {
  getSecret: (tenantId) => installStore.find(tenantId)?.webhookSecret,   // webhook ile AYNI imza şeması
});
if (!req) return res.status(401).json({ error: 'invalid_signature' });
// ZORUNLU dedupe: aynı req.requestId tekrar gelirse YENİDEN KESME (önceki yanıtı dön) — mükerrer fatura yasal sorun.

const { to, amount, items, reference } = req.payload;
// amount.total KURUŞ (integer). to.customerId → KENDİ customers:read'inle VKN/unvan/adres çöz (fatura başlığı).
// … GİB/e-fatura entegratörüne (Paraşüt/Uyumsoft…) kes …
res.json(capabilityResponse('accepted', { providerMessageId: invoiceNo })); // 'accepted' (async) veya 'issued' (anında)

import type { InvoiceStatusReport, InvoiceStatusEventData } from '@restomenum/plugin-sdk';

// SAĞLAYICI — GİB sonucu geldiğinde (dakikalar sürebilir) asenkron durum raporla:
await client.capabilities.reportStatus('invoice.issue', {
  requestId,                       // invoke yanıtındaki requestId
  status: 'issued',                // 'issued' | 'paid' | 'void' | 'failed'
  providerMessageId: invoiceNo,    // fatura no/UUID
} satisfies InvoiceStatusReport);

// TÜKETİCİ — invoice.status event'ine abone ol (yalnız İSTEK SAHİBİNE hedefli teslim, broadcast YOK):
// webhook handler'ında env.type === 'invoice.status':
const data = env.data as InvoiceStatusEventData;   // { requestId, status, providerMessageId?, error? }
// data.status: issued→paid ileri gider; void/failed terminal. requestId ile kendi kaydınla eşle.