@heywinit/chat-flows

Conversation flow engine for the Vercel Chat SDK. Build linear, multi-turn conversational flows with automatic routing and state management.

Features

• Fluent API: Type-safe FlowBuilder for defining conversation steps.
• Automatic Routing: FlowRouter manages thread subscriptions and resumes flows based on stored state.
• Validation: Built-in and custom validators for user input.
• Dynamic Content: Questions can be static strings or dynamic functions based on current flow data.
• State Management: Integrates with the Chat SDK's state adapters to persist progress across restarts.
• Lifecycle Hooks: Define custom behavior for flow completion and abandonment.

Installation

pnpm add @heywinit/chat-flows

Basic Usage

import { createFlow, FlowRouter, required, isEmail } from '@heywinit/chat-flows';

// 1. Define your data structure
interface OnboardingData {
  name: string;
  email: string;
}

// 2. Create the flow
const onboardingFlow = createFlow<OnboardingData>('onboarding')
  .ask('name', "Hey! What's your name?", {
    validate: required,
  })
  .ask('email', (ctx) => `Nice to meet you, ${ctx.data.name}! What's your email?`, {
    validate: isEmail,
  })
  .done(async (ctx, thread) => {
    await thread.post(`🎉 Welcome aboard, ${ctx.data.name}!`);
  });

// 3. Setup the router
const router = new FlowRouter(bot);
router.register(onboardingFlow);

// 4. Start the flow
bot.onNewMention(async (thread, message) => {
  await router.start('onboarding', thread, message);
});

Technical Details

FlowRouter

The FlowRouter is the orchestrator. It listens for messages on subscribed threads and attempts to resume active flows.

• register(flow): Adds a flow definition to the router.
• start(flowName, thread, message, initialData?): Initiates a new flow instance.
• abandonKeywords: Configurable keywords (default: cancel, stop, quit) that trigger the onAbandon hook.

FlowBuilder

Created via createFlow<T>(name).

• .ask(key, question, options):
  • key: The property in your data object where the response is stored.
  • question: A string or (ctx) => string.
  • options.validate: A function or array of functions (val) => string | true.
• .done(handler): Executed when all steps are completed successfully.
• .onAbandon(handler): Executed if the user sends an abandon keyword.

Validators

The package exports several common validators:

• required
• minLength(n)
• maxLength(n)
• isEmail
• oneOf([...])
• composeValidators(...validators)

License

MIT