Skip to main content

Architecture: hbf-core-api

C4 Component Diagram​

Key Flows​

Instantiation and Request Lifecycle​

const client = new HBFCoreApi("https://core.helvia.io", jwtToken);
const deployment = await client.BotDeploymentClient.findByHandle("my-bot");
  1. HBFCoreApi constructor stores url and token. No HTTP calls are made at construction time.
  2. Getter (e.g., .BotDeploymentClient) creates a new instance of the sub-client, passing this as the core client reference.
  3. Sub-client method builds the URL path and calls coreClient.requestHBFCore(method, path, payload?).
  4. requestHBFCore adds Authorization: Bearer <token> and Content-Type: application/json headers, then delegates to makeApiRequest.
  5. makeApiRequest calls axios. On network error (no response), it retries up to 3 times with exponential backoff (delay = (e^attempt - 2*random) * 1000 ms). On HTTP error response (non-2xx), it returns the response without throwing. On axios setup error, it returns a synthetic 503.
  6. The result is wrapped in HBFCoreApiResponse and returned to the sub-client.
  7. Sub-client calls the appropriate extractor (.getOptionalValue<BotDeployment>()) and returns the typed value or throws on error.

List Responses​

hbf-core returns paginated lists as { items: T[], page: number, pageSize: number, total: number }. HBFCoreApiResponse.getList<T>() reads body.items. TenantsClient.listPaged() handles multi-page collection by looping until all pages are fetched.

Resource Creation (ID Extraction)​

POST endpoints in hbf-core return the created resource ID either in the Location header (format: /{resource}/{id}) or in the response body as { id: string }. HBFCoreApiResponse.getSavedId(resource) handles both cases.

Shared Data Model​

All TypeScript interfaces live in src/datamodel/. They are re-exported from src/index.ts and consumed by other HBF services (hbf-bot, hbf-console, etc.) that import this package. Keeping types here ensures a single source of truth for the shared domain model across the Node.js ecosystem.