Deployment: hbf-core-api

This is an npm library, not a deployable service. There is no Docker image, no port, and no health check. "Deployment" means publishing a new version to the npm registry and updating consumer services.

Package Identity

Field	Value
Package name	@helvia/hbf-core-api
Registry	GitHub Packages (https://npm.pkg.github.com/)
Scope	@helvia
Current version	30.20.0 (see package.json)
Repository	https://github.com/Helvia/hbf-core-api

Publishing Workflow

There is no CI/CD workflow file in the repository (no .github/workflows/). Publishing is done manually from a local checkout:

npm run build   # compiles TypeScript -> dist/
npm publish     # pushes to GitHub Packages

npm run build runs tsc, which compiles src/ to dist/ using the config in tsconfig.json. The prepare script is an alias for build and also runs before npm publish.

Authentication for Publishing

Publishing to GitHub Packages requires a GitHub Personal Access Token with write:packages scope. Set it in your local ~/.npmrc:

//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>

What Gets Published

Controlled by .npmignore. The following are excluded from the published tarball:

tsconfig.json
/src
README.md
CONTRIBUTING.md
TODO
.prettierrc
/docs

The published package contains only the compiled output in dist/ and package.json. Consumers import from dist/src/index.js (CommonJS) and get types from dist/src/index.d.ts.

Versioning

The library uses semver. The major version increments when there are breaking changes to the exported API surface (renamed exports, removed fields, changed method signatures). Consumers pin with ^ (e.g. "@helvia/hbf-core-api": "^30.20.0"), accepting patch and minor updates automatically.

Version history: the current major is 30, indicating a long-lived library with many breaking iterations. Consumer version pins vary widely (hbf-broadcast is still on ^18.0.0), so not all services are on the latest version.

Consuming the Library

Registry Configuration

Consuming services must configure npm to fetch @helvia-scoped packages from GitHub Packages. This is done via .npmrc in the service repo:

@helvia:registry=https://npm.pkg.github.com
registry=https://registry.npmjs.org/

Authentication for Installation

A GitHub token with read:packages scope is required. In CI/CD environments this is injected as NODE_AUTH_TOKEN:

NODE_AUTH_TOKEN=<token> npm ci

Locally, set the token in ~/.npmrc:

//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>

package.json Dependency

"dependencies": {
  "@helvia/hbf-core-api": "^30.20.0"
}

Import Pattern

import { HBFCoreApi } from "@helvia/hbf-core-api";
import { BotDeployment, MessagingBackends, Tenant } from "@helvia/hbf-core-api";

Build Configuration

TypeScript (tsconfig.json)

Option	Value	Effect
target	ES2018	Output ES2018 JavaScript
module	commonjs	CommonJS output (compatible with Node.js require)
outDir	./dist	Compiled output directory
declaration	true	Generates .d.ts type declaration files
removeComments	true	Strips JSDoc comments from output
strict	true	All strict type-checking options enabled

The main and types fields in package.json point to ./dist/src/index.js and ./dist/src/index.d.ts respectively.

Build Scripts

npm run build   # tsc -- compiles to dist/
npm run docs    # typedoc --out docs  (generates API reference, excluded from publish)
npm test        # eslint ./src/**/*.ts && jest
npm run lint    # eslint ./src/**/*.ts

No Runtime Environment Variables

This library has no process environment of its own. All configuration (hbf-core URL, auth token) is passed by the consuming service at instantiation time. The consuming service is responsible for reading env vars and passing them to new HBFCoreApi(url, token).