Types Reference

Core TypeScript types exported by FlowKit. This is a concise reference; see source for full details.

Common Types

type JsonValue =
  | null
  | boolean
  | number
  | string
  | JsonValue[]
  | { [k: string]: JsonValue };

type Slots = Record<string, JsonValue>;

interface Logger {
  debug?: (message: string, meta?: Record<string, unknown>) => void;
  info?: (message: string, meta?: Record<string, unknown>) => void;
  warn?: (message: string, meta?: Record<string, unknown>) => void;
  error?: (message: string, meta?: Record<string, unknown>) => void;
}

Agent Types

interface AgentConfig {
  name: string;
  company?: string;
  personality?: string;
  language?: string;
  restrictions?: string[];
  context?: string;
  mode?: "flexible" | "strict";
  systemPrompt?: string;
  knowledgeBase?: KnowledgeBase;
}

interface Agent extends AgentConfig {
  readonly _brand: "Agent";
}

Extractor Types

type ExtractType =
  | "text"
  | "name"
  | "yesno"
  | "number"
  | "email"
  | "phone"
  | "date"
  | "url"
  | "time"
  | "currency"
  | "integer"
  | "percentage"
  | "address"
  | "zipcode"
  | "creditcard"
  | { oneOf: string[]; hints?: Record<string, string[]> }
  | { multiSelect: string[]; hints?: Record<string, string[]> }
  | { custom: string }
  | { regex: string; flags?: string; errorMessage?: string }
  | { range: { min?: number; max?: number; step?: number } }
  | { length: { min?: number; max?: number } }
  | { list: { separator?: string; minItems?: number; maxItems?: number } };

Flow Types

type SlotTransform =
  | "lowercase"
  | "uppercase"
  | "capitalize"
  | "trim"
  | "digits"
  | ((value: JsonValue) => JsonValue);

type StepCondition = (slots: Slots) => boolean;

interface StepConfig {
  id: string;
  message: string;
  extract?: ExtractType;
  slot?: string;
  next?: string;
  branches?: Record<string, string>;
  actions?: ActionConfig[];
  end?: boolean;
  retryMessage?: string;
  skipIf?: StepCondition;
  onlyIf?: StepCondition;
  confirm?: boolean | string;
  transform?: SlotTransform;
  delay?: number;
  tags?: string[];
  meta?: Record<string, JsonValue>;
  priority?: "low" | "normal" | "high" | "urgent";
  required?: boolean;
  defaultValue?: JsonValue;
  maxRetries?: number;
}

interface FlowConfig {
  id: string;
  agent: AgentConfig;
  initial: string;
  steps: Record<string, StepConfig>;
}

Action Types

interface ActionConfig {
  type: "tool" | "set" | "goto" | "end" | "inline" | "runFlow";
  tool?: string;
  payload?: JsonValue;
  slot?: string;
  value?: JsonValue;
  step?: string;
  fn?: (context: {
    conversationId: string;
    slots: Slots;
    currentStep: string;
  }) => Promise<void> | void;
  flowId?: string;
  flow?: FlowConfig;
}

Engine Types

interface EngineConfig {
  llm: LLMAdapter;
  storage: StorageAdapter;
  tools?: ToolsRegistry | ToolDefinition[];
  onEvent?: (event: EngineEvent) => void;
  maxRetries?: number;
  handoff?: boolean | Partial<HandoffConfig>;
  timeout?: TimeoutConfig;
  knowledgeBase?: KnowledgeBase;
  plugins?: Plugin[];
  logger?: Logger;
}

interface EngineOutput {
  message: string;
  done: boolean;
  state: { step: string; slots: Slots };
}

Event Types

type EngineEvent =
  | { type: "flow:start"; conversationId: string; step: string }
  | { type: "flow:end"; conversationId: string; slots: Slots }
  | { type: "step:enter"; conversationId: string; step: string }
  | { type: "step:exit"; conversationId: string; step: string; next: string }
  | { type: "user:message"; conversationId: string; text: string }
  | { type: "agent:message"; conversationId: string; text: string }
  | { type: "extract:success"; conversationId: string; extractType: string; value: JsonValue }
  | { type: "extract:fail"; conversationId: string; reason: string }
  | { type: "tool:call"; conversationId: string; tool: string; payload: JsonValue }
  | { type: "tool:result"; conversationId: string; tool: string; result: JsonValue }
  | { type: "handoff:detected"; conversationId: string; trigger: string; userMessage: string }
  | { type: "handoff:transfer"; conversationId: string; targetStep?: string }
  | { type: "timeout"; conversationId: string; timeoutType: "message" | "session" | "inactivity"; elapsed: number }
  | { type: "error"; conversationId: string; error: Error };

Adapter Types

interface LLMAdapter {
  chat(args: {
    systemPrompt: string;
    messages: Array<{ role: "user" | "assistant"; content: string }>;
    userMessage: string;
    responseSchema: JsonValue;
    tools?: ToolDefinition[];
  }): Promise<LLMResponse>;

  chatStream?(
    args: {
      systemPrompt: string;
      messages: Array<{ role: "user" | "assistant"; content: string }>;
      userMessage: string;
      responseSchema: JsonValue;
      tools?: ToolDefinition[];
    },
    onChunk: StreamHandler
  ): Promise<LLMResponse>;

  readonly supportsStreaming?: boolean;
  readonly supportsTools?: boolean;
}

interface LLMResponse {
  understood: boolean;
  extracted: JsonValue;
  confidence?: number;
  response: string;
  nextStep: string | null;
  actions?: ActionConfig[];
  reason?: string;
}

Storage Types

interface StorageAdapter {
  load(conversationId: string): Promise<ConversationState | null>;
  save(state: ConversationState): Promise<void>;
  delete(conversationId: string): Promise<void>;
}

Tools Types

interface ToolDefinition {
  name: string;
  description: string;
  parameters: {
    type: "object";
    properties: Record<string, {
      type: string;
      description?: string;
      enum?: string[];
    }>;
    required?: string[];
  };
  execute?: (params: Record<string, unknown>) => Promise<JsonValue | void> | JsonValue | void;
}

interface ToolsRegistry {
  register(name: string, handler: ToolHandler): this;
  has(name: string): boolean;
  call(name: string, payload: JsonValue, context: { conversationId: string; slots: Slots }): Promise<JsonValue | void>;
  list(): string[];
  getDefinitions(): ToolDefinition[];
}

type ToolHandler = (
  payload: JsonValue,
  context: { conversationId: string; slots: Slots }
) => Promise<JsonValue | void> | JsonValue | void;

Handoff Types

interface HandoffConfig {
  enabled: boolean;
  triggers?: string[];
  targetStep?: string;
  onHandoff?: (context: HandoffContext) => Promise<void> | void;
  message?: string;
}

interface HandoffContext {
  conversationId: string;
  userMessage: string;
  trigger: string;
  slots: Record<string, unknown>;
}

Timeout Types

interface TimeoutConfig {
  messageTimeout?: number;
  sessionTimeout?: number;
  inactivityTimeout?: number;
  onTimeoutStep?: string;
  onTimeout?: (context: TimeoutContext) => Promise<void> | void;
  timeoutMessage?: string;
}

Middleware Types

interface MiddlewareContext {
  conversationId: string;
  slots: Slots;
  currentStep: string;
  flowId: string;
  userMessage?: string;
  agentMessage?: string;
  extractedValue?: JsonValue;
  state: ConversationState;
  meta: Record<string, unknown>;
}

type NextFunction = () => Promise<void>;

type MiddlewareFn = (ctx: MiddlewareContext, next: NextFunction) => Promise<void> | void;

Channel Types

interface ChannelMessage {
  id: string;
  channel: ChannelType;
  senderId: string;
  text: string;
  timestamp: number;
}

interface ChannelResponse {
  text?: string;
  quickReplies?: Array<{ title: string; payload: string }>;
}

interface ChannelAdapter {
  channel: ChannelType;
  parseMessage(payload: unknown): ChannelMessage | null;
  formatResponse(response: ChannelResponse): unknown;
  send(recipientId: string, response: ChannelResponse): Promise<void>;
  getConversationId(message: ChannelMessage): string;
}