AI Brief: hbf-session-manager

hbf-session-manager is a NestJS microservice that periodically scans all tenants for idle chat sessions and marks them COMPLETED via hbf-core. It also manages per-organization webhook integrations that receive completed session payloads, auto-triggers connector flows and surveys through hbf-event-publisher, initiates LLM summarization of completed sessions via hbf-nlp, and auto-trains outdated NLP pipelines.

What This Repo Does

Two cron jobs run on configurable intervals. The first finds active ChatSession records in hbf-core whose last interaction is older than the per-tenant expireInactiveSessionAfter setting, verifies that any associated live chats are terminated, batch-marks them COMPLETED, triggers event-publisher flows and surveys, and POSTs the session data to any matching webhook integrations. The second detects NLP pipelines with tenantHasAutoTrain that are not up-to-date and trains them. A REST API allows admins to manage webhook integrations (URL, custom headers, tenant scope, error email recipients) per organization.

Tech Stack

• Language: TypeScript / Node.js
• Framework: NestJS 9
• Database: MySQL via TypeORM 0.3
• Key dependencies:
  • @helvia/hbf-core-api ^29.21.0 — typed client for hbf-core (tenants, chat sessions, NLP pipelines)
  • @nestjs/schedule — cron job scheduling
  • got 11 — HTTP client for webhook delivery and hbf-core REST calls
  • nodemailer + handlebars — error email notifications with HTML templates
  • moment-timezone — timezone-aware date handling
  • nestjs-pino + @elastic/ecs-pino-format — structured logging
  • elastic-apm-node — optional APM

Entry Points

• Main: src/main.ts
• App module: src/app.module.ts
• Config sample: .env.sample

Key Directories

Directory	Purpose
src/controllers/	REST API controllers for integrations and error listing
src/services/sessions/	Core business logic: session expiry, integration dispatch, email errors
src/services/scheduler/	Cron job setup for session checks and NLP pipeline checks
src/services/nlppipelines/	NLP pipeline auto-train orchestration
src/services/nlp-operations/	Lower-level NLP operations service
src/clients/hbf-core/	hbf-core API client (tenants, chat sessions, NLP pipelines, user auth)
src/clients/hbf-event-publisher/	HTTP client to trigger connector flows
src/clients/hbf-nlp/	HTTP client to request chat session LLM summarization
src/clients/http-client/	Base got-based HTTP client
src/entities/	TypeORM entities: SessionIntegration, SessionIntegrationHeader, SessionIntegrationError
src/migrations/	TypeORM migrations (run automatically on startup)
src/utils/templates/	Handlebars HTML template for error notification emails

API Surface

Base path: /organizations/:orgId/integrations/

• POST /organizations/:orgId/integrations/ — create a webhook integration
• GET /organizations/:orgId/integrations/ — list integrations for an org
• GET /organizations/:orgId/integrations/:integrationId — get a single integration
• PUT /organizations/:orgId/integrations/:integrationId — replace an integration
• DELETE /organizations/:orgId/integrations/:integrationId — delete an integration
• GET /organizations/:orgId/integrations/errors/:integrationId — list delivery errors for an integration

All endpoints require HBFGuard (hbf-core JWT) and OrgAdminOrModeratorGuard.

External Dependencies

• hbf-core: source of truth for tenants, sessions, NLP pipelines. Accessed via @helvia/hbf-core-api SDK and direct HTTP calls.
• hbf-event-publisher: receives chat-session-completed and survey-completed trigger events.
• hbf-nlp: receives summarizeChatSession requests for LLM summarization.
• MySQL: stores webhook integrations, custom headers, and delivery errors.
• SMTP server: sends error notification emails via nodemailer when webhook delivery fails.

Running Locally

# Copy env sample and fill in values
cp .env.sample .env

# Install dependencies
npm install

# Start in watch mode (APM disabled)
npm run start:dev

Tests

# Unit tests
npm run test

# Coverage
npm run test:cov