Data Model: hbf-core-api

TypeScript types exported from src/datamodel/ and re-exported from src/index.ts. These mirror hbf-core's MongoDB document schemas. Consuming services import these types to stay in sync with the shared domain model.

Overview

All interfaces and enums live in src/datamodel/. They are re-exported wholesale from src/index.ts. There is no runtime validation -- the library trusts that hbf-core returns conformant JSON. Types are cast, not parsed.

Utility Types (src/datamodel/util.ts)

Export	Kind	Purpose
LanguageCodes	enum	Supported BCP 47 language codes (en, el, es, pt, pt-br, etc.)
Localized<T>	type	Partial<Record<LanguageCodes, T>> -- localized variant of any type
PartialBy<T, K>	type	Makes specific fields of T optional. Used for create/update forms.
getStringURLSearchParams	function	Converts a params object to a URL query string, omitting null/undefined/empty values.

Core Domain Interfaces

Tenant (src/datamodel/tenant.ts)

Maps to hbf-core's Tenant MongoDB document.

Interface/Type	Purpose
Tenant	Primary bot (tenant) document: id, displayName, organizationId, content, powerups, settings, systemSettings, nluAgents, nlpMap, etc.
TenantUsageDto	Usage stats response: totalChatSessions, totalMessages per tenant.
CoreConfig	Convenience type for holding a { baseUrl, token } pair.
ComponentTree / ComponentTreeNode	Recursive tree structure describing the runtime pipeline for a tenant.

Key enums in this file:

Enum	Values (selected)
MessagingBackends	FACEBOOK, LOCAL, MICROSOFT_WEB_CHAT, MICROSOFT_TEAMS, VIBER, SLACK, INSTAGRAM, WHATSAPP, ZENDESK, API, ...
EventOrigin	Superset of MessagingBackends -- adds ITC (inter-tenant communication).
Powerup	FAQS, BROADCASTS, FLOWS, LIVECHAT, ANALYTICS, INTEGRATIONS, BILLING, MONITORING, ...

Organization (src/datamodel/organization.ts)

Interface	Fields
Organization	id, displayName, analytics, users, timezone, image, externalId, dataRetentionPeriod, auditLogsRetentionPeriod

User and Subscriber (src/datamodel/user.ts)

Export	Kind	Purpose
User	interface	Platform user: id, email, fullName, isModerator, tenantRoles, organizationRoles
UserForm	type	PartialBy<User, "id"> -- create/update form
Subscriber	interface	End-user (bot subscriber): id, handle, fullName, blackboard, customData, discriminator
SubscriberForm	interface	Create/update payload for subscribers
TeamsMember	interface	Microsoft Teams user representation
TenantRole	enum	HBF_TENANT_ADMIN, HBF_TENANT_EDITOR, HBF_TENANT_VIEWER, HBF_TENANT_LIVE_AGENT, HBF_TENANT_LIVE_AGENT_ADMIN
OrganizationRole	enum	HBF_ORG_ADMIN, HBF_ORG_EDITOR, HBF_ORG_VIEWER, HBF_ORG_LIVE_AGENT, HBF_ORG_LIVECHAT_ADMIN, HRWIZ_EMPLOYEE
TenantRolesTable	type	Map<string, Map<string, TenantRole[]>>
OrganizationRolesTable	type	Map<string, OrganizationRole[]>
TenantGrants / OrganizationGrants	enum	Deprecated. Use TenantRole / OrganizationRole.

Bot Deployment (src/datamodel/botDeployment.ts)

Export	Kind	Purpose
BotDeployment	interface	Deployment of a bot to a channel: id, handle, platform, scope, settings, isPreview
BotDeploymentForm	type	PartialBy<BotDeployment, "id" | "handle">
BotDeploymentScope	enum	USER, SYSTEM
BotDeploymentSettings	interface	layout + integration settings + language
BotDeploymentLayoutSettings	interface	Per-platform look-and-feel settings
BotDeploymentIntegrationSettings	interface	Per-platform channel integration credentials
Per-platform integration interfaces	interfaces	MicrosoftTeamsIntegrationSettings, FacebookIntegrationSettings, SlackIntegrationSettings, ViberIntegrationSettings, WebchatIntegrationSettings, InstagramIntegrationSettings, WhatsAppIntegrationSettings, ZendeskIntegrationSettings

The handle field encodes platform-specific identifiers (e.g. <AZURE_BOT_HANDLE>***<AZURE_TENANT_ID> for Teams, <FB_PAGE_ID> for Facebook).

Chat Session (src/datamodel/chat_session.ts)

Export	Kind	Purpose
ChatSessionDTO	interface	Full session read model: messages, intents, liveChats, variables, metadata, CSAT surveys
ChatSessionForm	interface	Write payload for creating/updating sessions
ChatSessionMessageDTO	interface	Individual message read model
ChatSessionMessageForm	interface	Individual message write payload
ChatSessionCSATSurvey	interface	CSAT survey result embedded in a session
ChatSessionVariableMapping	interface	Session variable name/value pair
LiveChatSessionDto	interface	Live chat sub-session: waitingTime, duration, responseTimes, agents
ChatSessionConversationNode	interface	Node traversal record: nodeId + appearances
ChatSessionBatchSetStatusCompleted	interface	Batch status-update payload: { ids: string[] }
ChatSessionStatuses	enum	ACTIVE, COMPLETED
ChatSessionMessageType	enum	TEXT, POSTBACK, ATTACHMENT, TRIGGER
ChatSessionMessageCategory	enum	COMMON, FEEDBACK, FALLBACK, LIVE_CHAT, BACK
LiveChatSender	enum	END_USER, AGENT
LiveChatEventType	enum	18 values covering the full livechat lifecycle (LIVECHAT_INITIALIZED through LIVECHAT_GENERIC_ERROR)

Broadcast (src/datamodel/broadcast.ts)

Export	Kind	Purpose
Broadcast	interface	Broadcast document: label, platform, type, status, choices, elastic
BroadcastForm	interface	Create/update payload
ResponseBroadcast	interface	Individual subscriber response to a broadcast
ResponseBroadcastForm	interface	Write payload for a broadcast response
BroadcastChoice	interface	Single choice in a poll/quiz broadcast
BroadcastTypes	enum	MESSAGE, POLL, QUIZ, ANALYTICS_REPORT
BroadcastStatuses	enum	PENDING, SENDING, WAITING, COMPLETE, INACTIVE, ERROR
BroadcastMethods	enum	BATCHES, ONE_SHOT

NLU (src/datamodel/nlu.ts)

Export	Kind	Purpose
NluAgent	interface	NLU agent config: name, configuration (type + provider settings), threshold, status
TenantNluAgent	interface	Tenant-scoped agent reference with isPrimary flag
NluAgentForm	type	Create/update form
NLUDetectionDto	interface	NLU detection result: triggeredIntentName, score, parameters
NluTypes	enum	DIALOGFLOW, LUIS, WIT, OPEN_AI, HELVIA_NLU
NLUStatus	enum	CREATED, OUTDATED, SYNCING, TRAINING, FAILED, READY, INITIALIZING

NLP Pipeline (src/datamodel/nlp.ts)

Export	Kind	Purpose
NLPPipeline	interface	Base NLP pipeline document: name, language, type, status, trainCount, nlpService
NLPPipelineForm	type	Create/update form
NLPPipelineTreeHeader	interface	Lightweight pipeline reference with variables list
NLPProcessDto	interface	NLP processing result: matchedCorpus, generatedText, extractedParameters
DialogflowNLP, LuisNLP, HelviaNLP, HelviaGPT	interfaces	Provider-specific pipeline extensions
NLPType	enum	LUIS_NLP, OPENAI_NLP, HELVIA_NLP, DIALOGFLOW_NLP, HELVIA_GPT
NLPStatus	enum	CREATED, OUTDATED, TRAINING, FAILED, READY, INITIALIZING

Integration (src/datamodel/integration.ts)

Export	Kind	Purpose
Integration	interface	Base integration: id, organizationId, name, type, category
OpenAIIntegration, AzureAIIntegration, GeminiAIIntegration	interfaces	LLM provider configs
OIDCIntegration	interface	OIDC authentication integration
AzureBlobStorageKbIntegration	interface	Azure Blob KB integration
SharePointKbIntegration	interface	SharePoint KB integration (see below)
SharepointSubscriptionInfo	interface	Lightweight view of a SharePoint integration's subscription state
IntegrationType	enum	OPENID_AUTHENTICATION, MICROSOFT_DYNAMICS_CRM, OPEN_AI_LLM, AZURE_AI_LLM, ZENDESK_LIVECHAT, GENESYS_LIVECHAT, SHAREPOINT_KB, ...
IntegrationCategory	enum	AUTHENTICATION, CRM, KB, TICKETING, LIVECHAT, LLM
OIDCGrantType	enum	AUTHORIZATION_CODE, AUTHORIZATION_CODE_PKCE

SharePointKbIntegration extends Integration:

Field	Type	Notes
tenantId	string	Azure AD tenant
siteUrl	string	SharePoint site URL (e.g. https://contoso.sharepoint.com/sites/MySite)
driveNames	string[]	Document library names to sync
webhookKey	string?	Webhook validation key
allowedContentTypes	string[]?	MIME type filter
webhookSubscriptionIds	Record<string, string>?	Map of driveName to Graph subscription ID
webhookSubscriptionExpiries	Record<string, string>?	Map of driveName to expiry ISO timestamp
deltaLinks	Record<string, string>?	Map of driveName to Graph delta link
lastSubscriptionRenewalCheck	string?	ISO timestamp of last renewal check
syncManagedMetadata	boolean?	Enable taxonomy/managed-metadata sync (default true, opt-out via false)
syncRbacPermissions	boolean?	Enable per-item RBAC permission sync (default true, opt-out via false)

Knowledge Base (src/datamodel/knowledgeBase.ts)

Export	Kind	Purpose
KnowledgeBase	interface	KB document: name, organization, languages, type, integrationId, status
KnowledgeBaseForm	type	PartialBy<KnowledgeBase, "id">
KnowledgeBaseLanguage	interface	Language entry with isPrimary flag
TenantAssociationRef	interface	{ tenantId, useGenerative }
KnowledgeBaseType	enum	INTERNAL, INTEGRATION, SHARED

Knowledge Base Article (src/datamodel/knowledgeBaseArticle.ts)

Export	Kind	Purpose
KnowledgeBaseArticleDto	interface	Article read model: id, groupId, ordinal, content[], metadata?, createdAt, updatedAt
KnowledgeBaseArticleForm	type	PartialBy<KnowledgeBaseArticleDto, "id">
ArticleContent	interface	Per-language content: languageCode, title?, tags?, body?
ArticleMetadata	type	Union of provider-specific metadata types (currently SharePointArticleMetadata)
SharePointArticleMetadata	interface	{ type: SHAREPOINT_KB, managedMetadata?: ManagedMetadataEntry[], permissions?: SharePointPermissions }
ManagedMetadataEntry	interface	{ fieldName, termLabel, termGuid } -- single taxonomy term from a managed metadata column
SharePointPermissions	interface	{ permissionsFetchedAt, sharingLinks: SharingLink[], grants: PermissionGrant[] }
SharingLink	interface	{ scope, type, webUrl, expirationDateTime?, grantedTo?: PermissionGrant[] }
PermissionGrant	interface	{ displayName, email?, roles: string[], identityType? }

ArticleMetadata is populated during sync when the corresponding subscription toggles (syncManagedMetadata, syncRbacPermissions) are enabled on the integration.

Analytics (src/datamodel/analytics.ts)

Export	Purpose
AnalyticsSummaryDto	Engagement, sessions, interactions, users stats
AnalyticsLiveChatDto	Live chat usage, missed chats, response/duration times
AnalyticsInterviewsDto	Interview session outcomes
AnalyticsDecisionTreesDto	Decision tree traversal counts
AnalyticsAutomatedAnswersDto	Automated answer usage counts
AnalyticsMissedQuestionsDto	Missed NLU questions + histogram
AnalyticsUserFeedbackDto	Feedback scores per bot/livechat/agent
AnalyticsCSATDto	CSAT overall + section scores + overtime
TenantFilterDto	Analytics filter: tenant + optional deployment list
AnalyticsTypes	enum: SUMMARY, LIVE_CHAT, INTERVIEWS, DECISION_TREES, AUTOMATED_ANSWERS, USER_FEEDBACK, MISSED_QUESTIONS, CSAT

Other Datamodel Files

File	Key exports
src/datamodel/handover.ts	HandoverLinkDTO, HandoverLinkForm, HandoverStatuses enum (PENDING, ACTIVE, COMPLETED, MISSED, DECLINED)
src/datamodel/fb_handover.ts	Facebook-specific handover types
src/datamodel/messaging_app.ts	Per-platform app configuration interfaces (FacebookAppConfiguration, SlackAppConfiguration, etc.)
src/datamodel/tenantSettings.ts	TenantSettings, TenantSystemSettings, TenantSecuritySettings (OIDC + pre-auth config), PreAuthTokenProvider (name, aud, jwksUri, refreshTokenEndpoint), TenantSecurityOidcSettings, and nested settings interfaces
src/datamodel/subscription_plan.ts	SubscriptionPlan, Subscription
src/datamodel/stats.ts	Stats ({ lastStatsUpdate, data })
src/datamodel/survey.ts	Survey
src/datamodel/group.ts	Group
src/datamodel/userGroup.ts	UserGroup
src/datamodel/blackboard.ts	Blackboard (session context) types
src/datamodel/effects.ts	Conversation effect types
src/datamodel/plugin.ts	Plugin<T> integration plugin types
src/datamodel/translation.ts	Translation types
src/datamodel/knowledgeBaseArticle.ts	KnowledgeBaseArticleDto, ArticleMetadata, SharePointArticleMetadata (see below)
src/datamodel/knowledgeBaseGroup.ts	KnowledgeBaseGroup
src/datamodel/audit_log.ts	AuditLog, CreatedByDto
src/datamodel/botContent.ts	Exports 50+ types including ConversationNode, Activity, ActivityCompiled, BotContent, BotContentCompiled, and various Response types. Referenced by all bot-content-related operations.

Request/Response Pattern

hbf-core list endpoints return:

{ "items": [...], "page": 1, "pageSize": 20, "total": 150 }

HBFCoreApiResponse.getList<T>() reads .items. Consumers call TenantsClient.listPaged() for multi-page iteration.

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

Relationship to MongoDB

These interfaces model hbf-core's MongoDB documents directly. There is no ORM mapping -- hbf-core serializes its Spring Data MongoDB documents to JSON, and this library deserializes that JSON into the typed interfaces listed above. Field names use camelCase to match hbf-core's JSON serialization output.