Skip to main content

AI Brief: hbf-client-integrations

NestJS service that acts as a multi-tenant integration hub, bridging client-specific third-party systems (CRMs, messaging platforms, SOAP services, and databases) with the Helvia Bot Framework (hbf-core). Each distributor module encapsulates one client or channel integration behind a common REST API protected by HBF JWT guards.

What This Repo Does​

Receives HTTP requests from client bots and translates them into calls to external systems: CRM APIs (Dynamics 365, Zendesk, Genesys), SOAP services (SITA AMS for airports, Wheelsys), messaging platforms (Facebook Messenger, Viber via Infobip), and custom client APIs. Each client has its own NestJS module under src/distributor/<client>/. A shared ClientModule provides reusable HTTP, S3, SOAP, and database client services to all distributor modules.

Tech Stack​

  • Language: TypeScript
  • Framework: NestJS 9
  • Key dependencies: TypeORM 0.3, @nestjs/axios, @nestjs/schedule, @aws-sdk/client-s3, nestjs-soap, nestjs-i18n, nestjs-pino, elastic-apm-node, openai, mssql, mysql2

Entry Points​

  • Main: src/main.ts (standard NestJS bootstrap calling AppModule.register())
  • App module: src/app.module.ts
  • ORM configs: ormconfig.ts, ormconfig-novibet_viber.ts, ormconfig-sixt.ts

Key Directories​

DirectoryPurpose
src/app.module.tsRoot module; conditionally wires database-backed modules at startup
src/distributor/One subdirectory per client/integration (see Supported Clients below)
src/distributor/clients/Shared HTTP, S3, SOAP, and external API client services
src/distributor/common/Shared DTOs, guards, utilities
src/guards/HBFGuard (JWT) and OrgMemberGuard (org membership)
src/database.config.tsFactory functions for per-client TypeORM configurations
src/i18n/i18n translation files (nestjs-i18n)
assets/SOAP WSDL files (SITA AMS, Wheelsys)
views/Handlebars (hbs) templates for email and report views

Supported Clients / Modules​

  • snappi: Upload finished conversations to Pobuca Measure and create incidents in Dynamics 365 CRM.
  • novibet: Zendesk ticket management; Genesys live-agent handoff; Viber-specific flows with a dedicated MySQL database and migration set.
  • helix: Helix-specific integrations (HTTP-based).
  • generali: GS400 API calls and Genesys Cloud live-agent handoff.
  • esy: ESY-specific integrations.
  • ppc: PPC-specific integrations.
  • viva: Viva-specific integrations.
  • cb-bot-api: Internal Chatbricks Bot API bridge.
  • aia (Athens International Airport): SITA AMS SOAP for flight data, Facebook Messenger messaging, S3 image sync, scheduled cron jobs; MySQL database.
  • actionLine: Action Line / Microsoft online meeting scheduling.
  • sixt: Rental details lookup (Wheelsys SOAP), driver greeting via Infobip (Viber/WhatsApp/SMS), delivery/click webhook receipts from Infobip; internal MySQL + external Azure SQL databases.
  • kelly-ai-agents: Kelly AI Agents API bridge (conditionally loaded).

External Dependencies​

  • Auth: JWT via @nestjs/jwt; HBFGuard validates tokens signed by hbf-core. OrgMemberGuard checks organisation membership.
  • Storage: AWS S3 via @aws-sdk/client-s3 (AIA image storage).
  • Database: TypeORM with MySQL (main, novibet-viber, sixt internal) and Azure SQL/MSSQL (sixt external).
  • Observability: Elastic APM (elastic-apm-node), structured logging via nestjs-pino + ECS format.
  • External APIs: Zendesk REST, Genesys Cloud SDK (purecloud-platform-client-v2), Infobip REST, Microsoft Dynamics 365 / Dataverse, Facebook Graph, Pobuca Measure, SITA AMS SOAP, Wheelsys SOAP, OpenAI.

Running Locally​

npm run start:dev

APM is disabled automatically in dev mode (ELASTIC_APM_ACTIVE=false).

Tests​

npm test              # unit tests (Jest)
npm run test:cov      # with coverage
npm run test:e2e      # end-to-end (jest-e2e.json)