Přeskočit na hlavní obsah

Adapter contract

PlatformAdapter rozhraní je seam mezi casinocrm.io a vaší casino platformou. Každá casino platforma má svůj vlastní bonus engine, KYC flow a webhook scheme; nesnažíme se být API každé platformy — poskytujeme stabilní kontrakt, který platformy implementují jednou.

Pro úplnou specifikaci viz Adapter integration. Tato stránka je konceptuální přehled.

Rozhraní​

interface PlatformAdapter {
  readonly slug: string;                    // 'acme-prod', 'zero', ...
  readonly displayName: string;
  readonly capabilities: AdapterCapabilities; // deklaruje, co podporuje

  bonus?: BonusOps;     // grantBonus, cancelBonus, getBonusStatus
  kyc?: KYCOps;         // initiateKYC, queryKYCStatus, updateKYCStatus
  rg?: ResponsibleGamingOps; // setSelfExclusion, setLimit, atd.
  wallet?: WalletOps;   // getBalance, snapshot streams
}

Každý ops bag je volitelný. Adapter, který nepodporuje KYC, prostě nechá kyc undefined — registry nesměruje žádné KYC ops na něj.

Capabilities​

Každý adapter deklaruje statické capabilities:

interface AdapterCapabilities {
  verticals: readonly Vertical[];           // casino, sportsbook, ...
  bonus: { issue, cancel, query_status }   // booleans
  kyc:   { initiate, query, update, webhooks }
  rg_features: readonly RGFeature[];
  wallet: { balance_pull, balance_push }
  signature_scheme: "hmac_sha256" | "hmac_sha512" | "rsa";
}

Effective capabilities = tenant.config ∩ adapter.capabilities. Pokud tenant chce deposit_limit_daily, ale adapter nepodporuje, feature spadne do CRM-only enforcement (capability_mock pattern) — limit se trackuje v CRM, ale platforma se nedozví.

Bidirectional flow​

Každá doména (bonus / KYC / RG) následuje stejný pattern:

CRM → Adapter (outbound):

  • Sync HTTP volání z bonus engine / admin akce.
  • Vrátí platform_*_id, který persistujeme pro korelaci.

Adapter → CRM (inbound):

  • Webhook dorazí na POST /v1/adapters/:slug/webhooks/{bonus,kyc}-events.
  • HMAC-SHA256 přes <timestamp>.<body> (Stripe-kompatibilní).
  • Idempotency dedupe přes webhook_events_processed (adapter_slug, event_id).
  • State sync: lifecycle události aktualizují doménový state pod RLS kontextem.

Adapter Zero — referenční​

Adapter Zero je in-process syntetický adapter, který shipujeme pro testing + demos. Deklaruje maximum capabilities (každý vertical, každý KYC flow, každá RG feature), takže testy procházejí celý povrch. Real-platform adaptery deklarují užší capabilities — co platforma skutečně podporuje.

Adapter Zero hraje obě strany: když CRM volá adapter.bonus.grantBonus(), AdapterZero zařadí synthetic webhook zpět přes receiver pomocí fastify.inject(). Stejné code paths jako real HTTP roundtrip — HMAC verifikace, idempotency, state sync — bez sítě.

Přidání nového adapteru​

Tři kroky:

  1. Vytvořte services/adapters/<your-platform>/ s mapováním kanonických událostí (události vaší platformy → kanonické události casinocrm.io).
  2. Implementujte rozhraní PlatformAdapter v apps/api/src/lib/bonus-adapter-<your-platform>.ts (nebo svou vlastní službu).
  3. Zaregistrujte adapter podle slug v bonus-adapter-registry.ts + přidejte HMAC secret resolver v bonus-webhooks.ts.

To je vše. Kompletní adapter má ~200-400 řádků TypeScriptu.