Skip to main content

AI Brief: hbf-core-api

TypeScript npm library that provides a typed HTTP client and shared data model for calling hbf-core. Every other Node.js service in the HBF platform imports this package to interact with hbf-core rather than making raw HTTP calls.

What This Repo Does​

hbf-core-api wraps the hbf-core REST API in a typed, axios-based client. It exports one root class (HBFCoreApi) that constructs domain-specific sub-clients on demand (TenantsClient, BotDeploymentClient, etc.). It also exports all shared TypeScript interfaces and enums (Tenant, Organization, BotDeployment, MessagingBackends, Powerup, etc.) so consumers have consistent types across the HBF ecosystem. The library handles auth headers, automatic JSON serialization, retry on network failure (up to 3 attempts, exponential backoff), and response unwrapping.

Tech Stack​

  • Language: TypeScript 5.5
  • Runtime: Node.js (CommonJS output via tsc)
  • HTTP client: axios 1.9
  • Utilities: lodash 4.17
  • Testing: Jest 29 + ts-jest
  • Linting: ESLint 9 + typescript-eslint
  • Docs generation: TypeDoc
  • Publish target: GitHub Packages (@helvia/hbf-core-api)

Entry Points​

  • Main: src/index.ts — re-exports HBFCoreApi, HBFCoreApiResponse, and all datamodel types
  • Core: src/core.ts — HBFCoreApi class and HBFCoreApiResponse class
  • Config: package.json, tsconfig.json

Key Directories​

DirectoryPurpose
src/clients/One client class per hbf-core resource domain
src/datamodel/TypeScript interfaces and enums matching hbf-core domain models
src/operator/Higher-level operator utilities (e.g., BotContent manipulation helpers)
src/core.tsHBFCoreApi root class + HBFCoreApiResponse response wrapper
src/index.tsPublic API surface — all exports
test/Jest tests

API Surface (if applicable)​

HBFCoreApi is instantiated with (url, token) and exposes these clients as getters:

GetterWraps hbf-core resource
TenantsClient/tenants — list, find, clone, create, update, delete, train NLU, stats, usage
OrganizationsClient/organizations — org CRUD
BotContentClientBot content authoring endpoints
BotDeploymentClient/bot-deployments and org-scoped deployment endpoints
ResponsesClientResponse template endpoints
AnalyticsClientAnalytics queries
BroadcastsClientBroadcast CRUD
GroupsClientGroup CRUD
UsersClientUser management
SubscribersClientSubscriber CRUD
UserGroupsClientUser group management
HandoverClientAgent handover management
FbHandoverClientFacebook-specific handover
ChatSessionsClientChat session queries
SurveyClientSurvey management
MessagingAppsClientMessaging app configuration
ElasticSearchClientElasticsearch proxy endpoints
NluDetectionClientNLU intent detection
NluAgentsClientNLU agent management
NlpPipelinesClientNLP pipeline CRUD
AuditLogsClientAudit log access
KnowledgeBaseArticleClientKnowledge base article CRUD
KnowledgeBaseClientKnowledge base CRUD
IntegrationClientIntegration config management
TranslationsClientTranslation management
KnowledgeBaseGroupClientKnowledge base group CRUD

HBFCoreApiResponse wraps every response and provides typed extraction:

  • .getValue<T>() — single object (throws on error)
  • .getOptionalValue<T>() — single object, undefined on 404
  • .getList<T>() — list response (reads body.items)
  • .getVoid() — validates 2xx, returns nothing
  • .getSavedId(resource) — extracts ID from Location header or response body
  • .getTotal() — extracts total count from response body
  • .getFile() — returns { data: ArrayBuffer, filename? } or undefined on 404

External Dependencies​

  • hbf-core (the REST API this library wraps) — URL configured at instantiation
  • hbf-auth (issues the JWT token passed to HBFCoreApi constructor)
  • No direct database or message queue connections

Running Locally​

npm install
npm run build   # compiles TypeScript to dist/
npm test        # eslint + jest

Tests​

npm test        # eslint ./src/**/*.ts && jest