chat-backend API

Everything the package exports, by the path you import it from. Open an export for its signature and options.

@evolve-framework/chat-backend

ChatBackendModule and all configuration types

Classes

ChatBackendModuleChat-backend HTTP module.

import { ChatBackendModule } from "@evolve-framework/chat-backend";

Registers the chat API routes on the consuming service's Fastify app. The handlers are Web-standard (Request → Response); a thin adapter bridges each one to Fastify, including streaming chat responses.

• POST /api/chat streams an answer, with tools from config.mcp or a GraphQL query tool for config.graphql. It allows 20 requests per minute per IP address.
• GET /api/chat and DELETE /api/chat load and delete the shopper's chat.
• GET /api/chats lists the shopper's chats.
• GET /api/widget/config serves the public settings the widget reads.
• GET /healthcheck answers 200, unless registerHealthcheck is false.

The module reads a few settings from the environment. Chats are stored in Redis with REDIS_URL, or in Upstash with UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN; without either, the chat routes other than POST /api/chat answer 503. Upstash also shares the rate limit across instances, which is otherwise kept in memory. LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY turn on Langfuse tracing.

Extends AbstractModule<unknown>

new ChatBackendModule(options: ChatBackendModuleOptions)

Option	Type	Description
config	ChatBackendConfig	The resolved single-tenant configuration for this deployment.
componentName?	string	Reported by GET /healthcheck. Defaults to "chat-backend".
basePath?	string	Mount all API routes under this path prefix (e.g. "/brand-a"). Defaults to "" (root). Required when combining multiple ChatBackendModule instances in one process (e.g. via CompositeModule) so their routes don't collide. A missing leading slash is added and a trailing slash is trimmed, so "brand-a", "/brand-a", and "/brand-a/" all mount at /brand-a.
registerHealthcheck?	boolean	Whether to register GET /healthcheck for this instance. Defaults to true. When combining multiple ChatBackendModule instances in one process, set this to false on all but one so there's a single canonical healthcheck for the container.

Types

AuthConfigAuthentication configuration.

import { type AuthConfig } from "@evolve-framework/chat-backend";

interface AuthConfig {
  cookies: CookieConfig;
  guestCookies?: CookieConfig;
  jwtCookie: string;
  guestJwtCookie?: string;
  validateAuthenticated: boolean;
  skipJwtValidation?: boolean;
  firstNameClaim: string;
  loginResponseType?: "direct" | "wrapped";
  allowAnonymous?: boolean;
}

BrandingBranding fallbacks exposed to the widget via /api/widget/config.

import { type Branding } from "@evolve-framework/chat-backend";

Presentation is owned by the storefront: the widget takes branding (logo, avatar, colors, header title) and labels from its own props, and only falls back to these values when a prop is absent. Every field is therefore optional — set only what a headless/propless consumer should still get.

interface Branding {
  name?: string;
  logoUrl?: string;
  avatarUrl?: string;
  greetingMessage?: string;
  placeholderText?: string;
  thinkingMessage?: string;
}

ChatBackendConfigComplete configuration for a single chat-backend deployment.

import { type ChatBackendConfig } from "@evolve-framework/chat-backend";

This is the single-tenant equivalent of the multi-tenant TenantConfig the original Next.js app resolved per request. The consuming service builds one of these (secrets/endpoints from env, structural fields committed in its own repo) and passes it to ChatBackendModule.

interface ChatBackendConfig {
  id: string;
  storeContext: StoreContext;
  locales?: LocaleOption[];
  auth: AuthConfig;
  graphql?: GraphQLConfig;
  model: ModelConfig;
  systemPrompt: string;
  schemaPath?: string;
  mcp?: MCPConfig;
  localTools?: Record<string, unknown>;
  maxToolSteps?: number;
  stopOnToolNames?: string[];
  transformTools?: ToolTransform;
  branding?: Branding;
  productUrls: ProductUrls;
  allowedOrigins: string[];
}

ChatBackendModuleConfigConfiguration for ChatBackendModule.

import { type ChatBackendModuleConfig } from "@evolve-framework/chat-backend";

export type ChatBackendModuleConfig = ChatBackendConfig;

CookieConfigCookie configuration for a session type (user or guest).

import { type CookieConfig } from "@evolve-framework/chat-backend";

interface CookieConfig {
  token: string;
  tokenHash?: string;
  refreshToken?: string;
  refreshTokenFlag: string;
  userData?: string;
}

GraphQLConfigGraphQL backend configuration.

import { type GraphQLConfig } from "@evolve-framework/chat-backend";

interface GraphQLConfig {
  endpoint: string;
  storeContextDelivery: "headers" | "variables" | "both";
  extraHeaders?: Record<string, string>;
  extraHeadersFromEnv?: Record<string, string>;
}

LocaleLabelsUI labels for a locale (consumed by the widget via /api/widget/config).

import { type LocaleLabels } from "@evolve-framework/chat-backend";

interface LocaleLabels {
  loginTitle: string;
  loginDescription: string;
  emailLabel: string;
  emailPlaceholder: string;
  passwordLabel: string;
  signIn: string;
  signingIn: string;
  loginError: string;
  loginNetworkError: string;
  greetingMessage: string;
  placeholderText: string;
  thinkingMessage: string;
}

LocaleOptionA selectable locale for this deployment.

import { type LocaleOption } from "@evolve-framework/chat-backend";

interface LocaleOption {
  id: string;
  label: string;
  storeKey: string;
  locale: string;
  labels?: LocaleLabels;
  overrideLabels?: Record<string, Record<string, string>>;
}

MCPConfigMCP (Model Context Protocol) server configuration.

import { type MCPConfig } from "@evolve-framework/chat-backend";

interface MCPConfig {
  endpoint: string;
  transport: "sse" | "http";
  headers?: Record<string, string>;
}

ModelConfigThe model a deployment uses, including the credentials to reach its provider.

import { type ModelConfig } from "@evolve-framework/chat-backend";

modelId is passed to the provider SDK — for Azure it is the deployment name, for OpenAI/Google the public model id. Azure providers additionally need an endpoint (the resource base URL; for azure-openai the deployment path is appended, for azure-ai-foundry it is used as-is) and an optional apiVersion.

type ModelConfig = {
  provider: "openai";
  modelId: string;
  apiKey: string;
} | {
  provider: "google";
  modelId: string;
  apiKey: string;
} | {
  provider: "azure-openai";
  modelId: string;
  apiKey: string;
  endpoint: string;
  apiVersion?: string;
} | {
  provider: "azure-ai-foundry";
  modelId: string;
  apiKey: string;
  endpoint: string;
  apiVersion?: string;
};

ModelProviderSupported AI providers.

import { type ModelProvider } from "@evolve-framework/chat-backend";

type ModelProvider = "openai" | "google" | "azure-openai" | "azure-ai-foundry";

ProductUrlsProduct URL patterns.

import { type ProductUrls } from "@evolve-framework/chat-backend";

The backend serves them to the widget through /api/widget/config unchanged; the widget builds product and category links with them.

interface ProductUrls {
  productUrlPattern: string;
  categoryUrlPattern?: string;
}

ResolvedChatBackendConfigConfig with labels resolved for the current request's locale.

import { type ResolvedChatBackendConfig } from "@evolve-framework/chat-backend";

interface ResolvedChatBackendConfig extends ChatBackendConfig {
  labels: LocaleLabels;
}

StoreContextStore context for GraphQL / MCP requests.

import { type StoreContext } from "@evolve-framework/chat-backend";

A request's x-storecontext-* headers override it. It also sets the language the assistant answers in, and it is part of the chat id, so a shopper has a separate chat per store, locale and currency.

interface StoreContext {
  storeKey: string;
  locale: string;
  currency: string;
}

ToolSetThe tools offered to the model, keyed by tool name.

import { type ToolSet } from "@evolve-framework/chat-backend";

type ToolSet = Record<string, unknown>;

ToolTransformReshapes the discovered tool set for a single request.

import { type ToolTransform } from "@evolve-framework/chat-backend";

type ToolTransform = (tools: ToolSet, ctx: ToolTransformContext) => ToolSet;

ToolTransformContextRequest-scoped data a transformTools hook may use.

import { type ToolTransformContext } from "@evolve-framework/chat-backend";

interface ToolTransformContext {
  storeContext: StoreContext;
  headers: Headers;
}

@evolve-framework/chat-backend/module

ChatBackendModule, the HTTP module with the chat API, and its option types

Classes

ChatBackendModuleChat-backend HTTP module.

import { ChatBackendModule } from "@evolve-framework/chat-backend/module";

Registers the chat API routes on the consuming service's Fastify app. The handlers are Web-standard (Request → Response); a thin adapter bridges each one to Fastify, including streaming chat responses.

• POST /api/chat streams an answer, with tools from config.mcp or a GraphQL query tool for config.graphql. It allows 20 requests per minute per IP address.
• GET /api/chat and DELETE /api/chat load and delete the shopper's chat.
• GET /api/chats lists the shopper's chats.
• GET /api/widget/config serves the public settings the widget reads.
• GET /healthcheck answers 200, unless registerHealthcheck is false.

The module reads a few settings from the environment. Chats are stored in Redis with REDIS_URL, or in Upstash with UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN; without either, the chat routes other than POST /api/chat answer 503. Upstash also shares the rate limit across instances, which is otherwise kept in memory. LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY turn on Langfuse tracing.

Extends AbstractModule<unknown>

new ChatBackendModule(options: ChatBackendModuleOptions)

Option	Type	Description
config	ChatBackendConfig	The resolved single-tenant configuration for this deployment.
componentName?	string	Reported by GET /healthcheck. Defaults to "chat-backend".
basePath?	string	Mount all API routes under this path prefix (e.g. "/brand-a"). Defaults to "" (root). Required when combining multiple ChatBackendModule instances in one process (e.g. via CompositeModule) so their routes don't collide. A missing leading slash is added and a trailing slash is trimmed, so "brand-a", "/brand-a", and "/brand-a/" all mount at /brand-a.
registerHealthcheck?	boolean	Whether to register GET /healthcheck for this instance. Defaults to true. When combining multiple ChatBackendModule instances in one process, set this to false on all but one so there's a single canonical healthcheck for the container.

Types

ChatBackendModuleConfigConfiguration for ChatBackendModule.

import { type ChatBackendModuleConfig } from "@evolve-framework/chat-backend/module";

export type ChatBackendModuleConfig = ChatBackendConfig;

@evolve-framework/chat-backend/config

ChatBackendConfig and the types it is built from, for a service that builds its configuration in a separate file

Types

AuthConfigAuthentication configuration.

import { type AuthConfig } from "@evolve-framework/chat-backend/config";

interface AuthConfig {
  cookies: CookieConfig;
  guestCookies?: CookieConfig;
  jwtCookie: string;
  guestJwtCookie?: string;
  validateAuthenticated: boolean;
  skipJwtValidation?: boolean;
  firstNameClaim: string;
  loginResponseType?: "direct" | "wrapped";
  allowAnonymous?: boolean;
}

BrandingBranding fallbacks exposed to the widget via /api/widget/config.

import { type Branding } from "@evolve-framework/chat-backend/config";

Presentation is owned by the storefront: the widget takes branding (logo, avatar, colors, header title) and labels from its own props, and only falls back to these values when a prop is absent. Every field is therefore optional — set only what a headless/propless consumer should still get.

interface Branding {
  name?: string;
  logoUrl?: string;
  avatarUrl?: string;
  greetingMessage?: string;
  placeholderText?: string;
  thinkingMessage?: string;
}

ChatBackendConfigComplete configuration for a single chat-backend deployment.

import { type ChatBackendConfig } from "@evolve-framework/chat-backend/config";

This is the single-tenant equivalent of the multi-tenant TenantConfig the original Next.js app resolved per request. The consuming service builds one of these (secrets/endpoints from env, structural fields committed in its own repo) and passes it to ChatBackendModule.

interface ChatBackendConfig {
  id: string;
  storeContext: StoreContext;
  locales?: LocaleOption[];
  auth: AuthConfig;
  graphql?: GraphQLConfig;
  model: ModelConfig;
  systemPrompt: string;
  schemaPath?: string;
  mcp?: MCPConfig;
  localTools?: Record<string, unknown>;
  maxToolSteps?: number;
  stopOnToolNames?: string[];
  transformTools?: ToolTransform;
  branding?: Branding;
  productUrls: ProductUrls;
  allowedOrigins: string[];
}

CookieConfigCookie configuration for a session type (user or guest).

import { type CookieConfig } from "@evolve-framework/chat-backend/config";

interface CookieConfig {
  token: string;
  tokenHash?: string;
  refreshToken?: string;
  refreshTokenFlag: string;
  userData?: string;
}

GraphQLConfigGraphQL backend configuration.

import { type GraphQLConfig } from "@evolve-framework/chat-backend/config";

interface GraphQLConfig {
  endpoint: string;
  storeContextDelivery: "headers" | "variables" | "both";
  extraHeaders?: Record<string, string>;
  extraHeadersFromEnv?: Record<string, string>;
}

LocaleLabelsUI labels for a locale (consumed by the widget via /api/widget/config).

import { type LocaleLabels } from "@evolve-framework/chat-backend/config";

interface LocaleLabels {
  loginTitle: string;
  loginDescription: string;
  emailLabel: string;
  emailPlaceholder: string;
  passwordLabel: string;
  signIn: string;
  signingIn: string;
  loginError: string;
  loginNetworkError: string;
  greetingMessage: string;
  placeholderText: string;
  thinkingMessage: string;
}

LocaleOptionA selectable locale for this deployment.

import { type LocaleOption } from "@evolve-framework/chat-backend/config";

interface LocaleOption {
  id: string;
  label: string;
  storeKey: string;
  locale: string;
  labels?: LocaleLabels;
  overrideLabels?: Record<string, Record<string, string>>;
}

MCPConfigMCP (Model Context Protocol) server configuration.

import { type MCPConfig } from "@evolve-framework/chat-backend/config";

interface MCPConfig {
  endpoint: string;
  transport: "sse" | "http";
  headers?: Record<string, string>;
}

ProductUrlsProduct URL patterns.

import { type ProductUrls } from "@evolve-framework/chat-backend/config";

The backend serves them to the widget through /api/widget/config unchanged; the widget builds product and category links with them.

interface ProductUrls {
  productUrlPattern: string;
  categoryUrlPattern?: string;
}

ResolvedChatBackendConfigConfig with labels resolved for the current request's locale.

import { type ResolvedChatBackendConfig } from "@evolve-framework/chat-backend/config";

interface ResolvedChatBackendConfig extends ChatBackendConfig {
  labels: LocaleLabels;
}

StoreContextStore context for GraphQL / MCP requests.

import { type StoreContext } from "@evolve-framework/chat-backend/config";

A request's x-storecontext-* headers override it. It also sets the language the assistant answers in, and it is part of the chat id, so a shopper has a separate chat per store, locale and currency.

interface StoreContext {
  storeKey: string;
  locale: string;
  currency: string;
}

ToolSetThe tools offered to the model, keyed by tool name.

import { type ToolSet } from "@evolve-framework/chat-backend/config";

type ToolSet = Record<string, unknown>;

ToolTransformReshapes the discovered tool set for a single request.

import { type ToolTransform } from "@evolve-framework/chat-backend/config";

type ToolTransform = (tools: ToolSet, ctx: ToolTransformContext) => ToolSet;

ToolTransformContextRequest-scoped data a transformTools hook may use.

import { type ToolTransformContext } from "@evolve-framework/chat-backend/config";

interface ToolTransformContext {
  storeContext: StoreContext;
  headers: Headers;
}

Not listed: 2 options types. They appear as the tables under the constructors and functions they type.