@yaebal/conversation

pnpm add @yaebal/conversation

import { Bot } from "@yaebal/core";
import { conversation, createConversation } from "@yaebal/conversation";

const greet = createConversation(async (cv, ctx) => {
  await ctx.send("what's your name?");
  const a = await cv.waitFor("message:text"); // narrowed: a.text is a plain string
  await a.send(`age, ${a.text}?`);
  const b = await cv.waitFor("message:text");
  await b.send(`${a.text} is ${b.text}`);
});

const bot = new Bot(process.env.BOT_TOKEN!)
  .install(conversation({ greet }));

bot.command("greet", (ctx) => ctx.conversation.enter("greet"));
bot.start();

const echo = createConversation(async (cv, ctx) => {
  // waitFor narrows exactly like composer.on() — no manual "if (!ctx.text) return"
  const a = await cv.waitFor("message:text");
  await ctx.send(`text: ${a.text}`);

  // waitUntil takes any predicate, sync or async — and narrows with a type guard overload
  const photo = await cv.waitUntil((c): c is typeof c & { message: { photo: unknown } } =>
    Boolean(c.message?.photo));
  await ctx.send("nice photo");
});

const signup = createConversation(async (cv, ctx) => {
  const name = await cv.form.text({ question: "your name?" });

  const age = await cv.form.int({
    question: `thanks, ${name}! how old are you?`,
    min: 1,
    max: 120,
    invalid: "age is a number between 1 and 120 — try again",
  });

  const plan = await cv.form.choice({
    question: "pick a plan: free, pro, or team",
    choices: ["free", "pro", "team"] as const,
  });

  const confirmed = await cv.form.confirm({ question: `lock in ${plan}? (y/n)` });
  if (!confirmed) return ctx.send("cancelled");

  await ctx.send(`saved: ${name}, ${age}, ${plan}`);
});

bot.install(conversation({ support }, {
  // an update that doesn't match the *currently parked* wait()/waitFor() filter:
  passthrough: true,                 // default: falls through to normal handlers
  // passthrough: false,             // queued instead (bounded by queueLimit)

  // /commands bypass an active conversation, so global handlers keep working
  passCommands: ["cancel", "help"],  // default true (every command)
}));

// a global /cancel that works mid-conversation — no per-step checks needed
bot.command("cancel", (ctx) =>
  ctx.conversation.active ? ctx.conversation.leave() : ctx.reply("nothing to cancel"));

import { ConversationTimeoutError } from "@yaebal/conversation";

const patient = createConversation(async (cv, ctx) => {
  try {
    const answer = await cv.waitFor("message:text", { timeout: 60_000 }); // per-call override
    await ctx.send(`got: ${answer.text}`);
  } catch (error) {
    if (error instanceof ConversationTimeoutError) return ctx.send("timed out — try again");
    throw error;
  }
});

bot.install(conversation({ patient }, {
  waitTimeout: 5 * 60_000, // default for every wait()/waitFor()/waitUntil()/form.* call
}));

// left uncaught, a timeout just ends the conversation — onLeave fires with reason "timeout"

const fetching = createConversation(async (cv, ctx) => {
  // aborts automatically if the conversation is left, replaced, or times out mid-fetch
  const res = await fetch("https://api.example.com/status", { signal: cv.signal });
  await ctx.send(await res.text());
});

import { conversation, perChat, perChatUser, perUser } from "@yaebal/conversation";

bot.install(conversation({ support }, {
  getKey: perChatUser, // default — one conversation per user *per chat*, group-safe
  // getKey: perChat,  // one shared conversation per chat (any member can answer)
  // getKey: perUser,  // one conversation per user, follows them across every chat
}));

import { conversation, createConversation } from "@yaebal/conversation";
import { redisStorage } from "@yaebal/sklad";
import Redis from "ioredis";

const support = createConversation(async (cv, ctx) => {
  await ctx.send("what's the problem?");
  const topic = await cv.waitFor("message:text");

  // non-deterministic or side-effecting work goes through cv.external() — its result is
  // recorded once and replayed, never re-executed
  const ticketId = await cv.external(() => createTicketId());

  await ctx.send(`ticket #${ticketId} queued: ${topic.text}`);
});

const bot = new Bot(process.env.BOT_TOKEN!)
  .install(conversation({ support }, {
    storage: redisStorage(new Redis()), // any StorageAdapter<unknown> — see @yaebal/sklad
  }));

// a restart now resumes users mid-conversation: every wait() answer, api call and
// cv.external() result replays from the log instead of firing again

bot.install(conversation({ support }, {
  onEnter: (ctx, info) => console.log("entered", info.name, info.params),
  onLeave: (ctx, info) => {
    // info.reason: "finish" | "left" | "replaced" | "timeout" | "error"
    if (info.reason === "finish") console.log("result:", info.result);
    if (info.reason === "error") console.error("conversation crashed:", info.error);
  },
  onError: (error, ctx, info) => reportToSentry(error, { conversation: info.name }),
  onOverflow: (dropped, ctx, info) => console.warn("dropped an update for", info.name),
}));

const survey = createConversation(async (cv, ctx) => {
  const a = await cv.waitFor("message:text");
  return { answer: a.text }; // read back via onLeave's info.result — see "hooks" above
});

// safe to fire and forget — the recommended style. enter()'s promise resolves once the
// conversation has *started* (bounded, fast), never once it *finishes* (which may need
// updates that arrive through this very handler — awaiting that would deadlock it)
bot.command("survey", (ctx) => ctx.conversation.enter("survey"));