Перейти до основного вмісту

Adapter contract

Translator note: machine-translated baseline. Needs human review by a native UK speaker. EN source is canonical.

Інтерфейс PlatformAdapter — це seam між casinocrm.io і вашою casino платформою. Кожна casino платформа має свій власний bonus engine, KYC flow і webhook scheme; ми не намагаємось бути API кожної платформи — ми надаємо стабільний контракт, який платформи реалізують один раз.

Для повної специфікації див. Adapter integration. Ця сторінка — концептуальний огляд.

Інтерфейс​

interface PlatformAdapter {
  readonly slug: string;                    // 'acme-prod', 'zero', ...
  readonly displayName: string;
  readonly capabilities: AdapterCapabilities; // декларує, що підтримує

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

Кожен ops bag — опційний. Adapter, який не підтримує KYC, просто залишає kyc undefined — registry не маршрутизує жодних KYC ops до нього.

Capabilities​

Кожен adapter декларує статичні 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. Якщо tenant хоче deposit_limit_daily, але adapter не підтримує, feature падає до CRM-only enforcement (capability_mock pattern) — limit трекається в CRM, але платформі не повідомляється.

Bidirectional flow​

Кожна domain (bonus / KYC / RG) дотримується того самого pattern:

CRM → Adapter (outbound):

  • Sync HTTP виклик з bonus engine / admin action.
  • Повертає platform_*_id, який ми persist для correlation.

Adapter → CRM (inbound):

  • Webhook hits POST /v1/adapters/:slug/webhooks/{bonus,kyc}-events.
  • HMAC-SHA256 над <timestamp>.<body> (Stripe-сумісне).
  • Idempotency dedupe через webhook_events_processed (adapter_slug, event_id).
  • State sync: lifecycle події оновлюють domain state під RLS context.

Adapter Zero — reference​

Adapter Zero — це in-process synthetic adapter, який ми shipимо для testing + demos. Він декларує maximum capabilities (кожен vertical, кожен KYC flow, кожен RG feature), тож тести вправляють весь surface. Real-platform adapters декларують вужчі capabilities — те, що платформа реально підтримує.

Adapter Zero грає обидва боки: коли CRM викликає adapter.bonus.grantBonus(), AdapterZero ставить synthetic webhook назад через receiver через fastify.inject(). Ті самі code paths, що real HTTP roundtrip — HMAC verification, idempotency, state sync — без мережі.

Додавання нового adapter​

Три кроки:

  1. Створіть services/adapters/<your-platform>/ з мапінгом канонічних подій (події вашої платформи → канонічні події casinocrm.io).
  2. Реалізуйте інтерфейс PlatformAdapter в apps/api/src/lib/bonus-adapter-<your-platform>.ts (або своїй власній службі).
  3. Зареєструйте adapter по slug в bonus-adapter-registry.ts + додайте HMAC secret resolver в bonus-webhooks.ts.

Це все. Повний adapter — це ~200-400 рядків TypeScript.