@henry-dev/botkit 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,2621 @@
+// matchers/matcher.literal.ts
+function escapeRegExp(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var hasRegexSyntax = (p) => /[\{\}\[\]\(\)\|\+\?\^\$]/.test(p);
+function createLiteralMatcher(patterns, opts) {
+  const normalizeText = (text) => {
+    if (opts?.normalize === false) {
+      return text.trim().toLowerCase();
+    }
+    let res = text.trim().toLowerCase();
+    res = res.replace(/[.,\/#!$%\^&\*;:{}=\-_`~()?"'’]/g, "");
+    res = res.replace(/(.)\1{2,}/g, "$1");
+    res = res.replace(/\s+/g, " ");
+    return res.trim();
+  };
+  const compilePattern = (pattern) => {
+    const normalized = normalizeText(pattern);
+    const hasRegex = hasRegexSyntax(normalized);
+    const escaped = hasRegex ? normalized : escapeRegExp(normalized);
+    const useBoundary = opts?.boundary ?? true;
+    if (useBoundary && !hasRegex) {
+      return `\\b${escaped}\\b`;
+    }
+    return escaped;
+  };
+  const exactPatterns = patterns.filter((p) => p !== "*");
+  const hasWildcard = patterns.includes("*");
+  const compiledExact = exactPatterns.map((pattern) => {
+    const regexStr = compilePattern(pattern);
+    return {
+      pattern,
+      regex: new RegExp(regexStr, "i")
+    };
+  });
+  const positiveRegExp = exactPatterns.length > 0 ? new RegExp(exactPatterns.map(compilePattern).join("|"), "i") : null;
+  const excludePatterns = opts?.excludeIf || [];
+  const negationRegExp = excludePatterns.length > 0 ? new RegExp(excludePatterns.map(compilePattern).join("|"), "i") : null;
+  return {
+    patterns,
+    normalize: normalizeText,
+    match: (text) => {
+      const normalizedInput = normalizeText(text);
+      if (negationRegExp && negationRegExp.test(normalizedInput)) {
+        return {
+          matched: false,
+          pattern: "",
+          confidence: 0
+        };
+      }
+      if (positiveRegExp && positiveRegExp.test(normalizedInput)) {
+        for (const item of compiledExact) {
+          if (item.regex.test(normalizedInput)) {
+            return {
+              matched: true,
+              pattern: item.pattern,
+              confidence: 1
+            };
+          }
+        }
+      }
+      if (hasWildcard) {
+        return {
+          matched: true,
+          pattern: "*",
+          confidence: 0.1
+        };
+      }
+      return {
+        matched: false,
+        pattern: "",
+        confidence: 0
+      };
+    }
+  };
+}
+function matchesAny(patterns, opts) {
+  return createLiteralMatcher(patterns, opts);
+}
+
+// core/builder.ts
+var CompileError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CompileError";
+  }
+};
+var ActionNodeBuilder = class {
+  constructor(bot, id, options) {
+    this.bot = bot;
+    this.id = id;
+    this._timeoutMs = 5e3;
+    this._text = "";
+    if (options) {
+      if (options.execute) this._actionFn = options.execute;
+      if (options.timeoutMs) this._timeoutMs = options.timeoutMs;
+      if (typeof options.onSuccess === "string") {
+        this._onSuccess = { targetNodeId: options.onSuccess };
+      } else if (options.onSuccess) {
+        this._onSuccess = options.onSuccess;
+      }
+      if (typeof options.onFailure === "string") {
+        this._onFailure = { targetNodeId: options.onFailure };
+      } else if (options.onFailure) {
+        this._onFailure = options.onFailure;
+      }
+      if (typeof options.onTimeout === "string") {
+        this._onTimeout = { targetNodeId: options.onTimeout };
+      } else if (options.onTimeout) {
+        this._onTimeout = options.onTimeout;
+      }
+    }
+  }
+  execute(fn) {
+    this._actionFn = fn;
+    return this;
+  }
+  timeout(ms) {
+    this._timeoutMs = ms;
+    return this;
+  }
+  text(msg) {
+    this._text = msg;
+    return this;
+  }
+  onSuccess(targetNodeId, handler) {
+    this._onSuccess = { targetNodeId, handler };
+    return this;
+  }
+  onFailure(targetNodeId, handler) {
+    this._onFailure = { targetNodeId, handler };
+    return this;
+  }
+  onTimeout(targetNodeId, handler) {
+    this._onTimeout = { targetNodeId, handler };
+    return this;
+  }
+  onEnter(fn) {
+    this._onEnter = fn;
+    return this;
+  }
+  onExit(fn) {
+    this._onExit = fn;
+    return this;
+  }
+  ask(text) {
+    return this.bot.ask(text);
+  }
+  action(id, options) {
+    return this.bot.action(id, options);
+  }
+  handoff(id, options) {
+    return this.bot.handoff(id, options);
+  }
+  global(matcher, options) {
+    return this.bot.global(matcher, options);
+  }
+  getId() {
+    return this.id;
+  }
+  getText() {
+    return this._text;
+  }
+  getActionFn() {
+    return this._actionFn;
+  }
+  getTimeoutMs() {
+    return this._timeoutMs;
+  }
+  getOnSuccess() {
+    return this._onSuccess;
+  }
+  getOnFailure() {
+    return this._onFailure;
+  }
+  getOnTimeout() {
+    return this._onTimeout;
+  }
+  getOnEnterFn() {
+    return this._onEnter;
+  }
+  getOnExitFn() {
+    return this._onExit;
+  }
+};
+var HandoffNodeBuilder = class {
+  constructor(bot, id, options) {
+    this.bot = bot;
+    this.id = id;
+    this._timeoutMs = 10 * 60 * 1e3;
+    this._text = "Connecting you with an agent. Please hold...";
+    this._queueMessage = "You are in the queue. An agent will be with you shortly.";
+    if (options) {
+      if (options.reason) this._reason = options.reason;
+      if (options.timeoutMs !== void 0) this._timeoutMs = options.timeoutMs;
+      if (options.resumeNodeId) this._resumeNodeId = options.resumeNodeId;
+      if (options.fallbackNodeId) this._fallbackNodeId = options.fallbackNodeId;
+      if (options.message) this._text = options.message;
+      if (options.queueMessage !== void 0) this._queueMessage = options.queueMessage;
+      if (options.metadata) this._metadata = options.metadata;
+    }
+  }
+  reason(text) {
+    this._reason = text;
+    return this;
+  }
+  timeout(ms) {
+    this._timeoutMs = ms;
+    return this;
+  }
+  resumeAt(targetNodeId) {
+    this._resumeNodeId = targetNodeId;
+    return this;
+  }
+  fallbackTo(targetNodeId) {
+    this._fallbackNodeId = targetNodeId;
+    return this;
+  }
+  message(text) {
+    this._text = text;
+    return this;
+  }
+  queueMessage(text) {
+    this._queueMessage = text;
+    return this;
+  }
+  metadata(data) {
+    this._metadata = data;
+    return this;
+  }
+  onEnter(fn) {
+    this._onEnter = fn;
+    return this;
+  }
+  onExit(fn) {
+    this._onExit = fn;
+    return this;
+  }
+  ignoreGlobals(ignore = true) {
+    this._ignoreGlobals = ignore;
+    return this;
+  }
+  ask(text) {
+    return this.bot.ask(text);
+  }
+  action(id, options) {
+    return this.bot.action(id, options);
+  }
+  handoff(id, options) {
+    return this.bot.handoff(id, options);
+  }
+  global(matcher, options) {
+    return this.bot.global(matcher, options);
+  }
+  getId() {
+    return this.id;
+  }
+  getText() {
+    return this._text;
+  }
+  getReason() {
+    return this._reason;
+  }
+  getTimeoutMs() {
+    return this._timeoutMs;
+  }
+  getResumeNodeId() {
+    return this._resumeNodeId;
+  }
+  getFallbackNodeId() {
+    return this._fallbackNodeId;
+  }
+  getQueueMessage() {
+    return this._queueMessage;
+  }
+  getMetadata() {
+    return this._metadata;
+  }
+  getOnEnterFn() {
+    return this._onEnter;
+  }
+  getOnExitFn() {
+    return this._onExit;
+  }
+  getIgnoreGlobals() {
+    return this._ignoreGlobals;
+  }
+};
+var GlobalTransitionBuilder = class {
+  constructor(bot, matcher, options) {
+    this.bot = bot;
+    this._patterns = [];
+    this._priority = "high";
+    if (typeof matcher === "object" && matcher !== null && "match" in matcher && typeof matcher.match === "function") {
+      this._matcher = matcher;
+      this._patterns = [...this._matcher.patterns];
+    } else if (typeof matcher === "string") {
+      this._patterns = [matcher];
+    } else if (Array.isArray(matcher)) {
+      this._patterns = [...matcher];
+    } else {
+      this._patterns = [];
+    }
+    if (typeof options === "string") {
+      this._targetNodeId = options;
+    } else if (options) {
+      if (options.id) this._id = options.id;
+      if (options.target) this._targetNodeId = options.target;
+      if (options.targetNodeId) this._targetNodeId = options.targetNodeId;
+      if (options.priority) this._priority = options.priority;
+      if (options.response) this._responseFn = options.response;
+      if (options.matcherOptions) this._opts = options.matcherOptions;
+    }
+  }
+  id(customId) {
+    this._id = customId;
+    return this;
+  }
+  then(targetNodeId) {
+    this._targetNodeId = targetNodeId;
+    return this;
+  }
+  response(fn) {
+    this._responseFn = fn;
+    return this;
+  }
+  priority(p) {
+    this._priority = p;
+    return this;
+  }
+  getId(defaultId) {
+    return this._id ?? defaultId;
+  }
+  getTargetNodeId() {
+    return this._targetNodeId;
+  }
+  getPatterns() {
+    return this._patterns;
+  }
+  getOpts() {
+    return this._opts;
+  }
+  getMatcher() {
+    return this._matcher;
+  }
+  getPriority() {
+    return this._priority;
+  }
+  getResponseFn() {
+    return this._responseFn;
+  }
+  ask(text) {
+    return this.bot.ask(text);
+  }
+  action(id, options) {
+    return this.bot.action(id, options);
+  }
+  handoff(id, options) {
+    return this.bot.handoff(id, options);
+  }
+  global(matcher, options) {
+    return this.bot.global(matcher, options);
+  }
+};
+var FlowNodeBuilder = class {
+  constructor(bot, defaultId, text) {
+    this.bot = bot;
+    this.defaultId = defaultId;
+    this.text = text;
+    this._branches = [];
+    this._fallbackText = "Please try again.";
+    this._maxRetries = 3;
+  }
+  getId() {
+    return this._customId ?? this.defaultId;
+  }
+  id(customId) {
+    this._customId = customId;
+    return this;
+  }
+  expect(matcher, opts) {
+    let patterns;
+    let customMatcher;
+    if (typeof matcher === "object" && matcher !== null && "match" in matcher && typeof matcher.match === "function") {
+      customMatcher = matcher;
+      patterns = [...customMatcher.patterns];
+    } else if (typeof matcher === "string") {
+      patterns = [matcher];
+    } else if (Array.isArray(matcher)) {
+      patterns = [...matcher];
+    } else {
+      patterns = [];
+    }
+    this._branches.push({
+      patterns,
+      opts,
+      matcher: customMatcher
+    });
+    return this;
+  }
+  then(targetNodeId) {
+    if (this._branches.length === 0) {
+      throw new Error(`Cannot call then("${targetNodeId}") before expect() on node "${this.getId()}"`);
+    }
+    const lastBranch = this._branches[this._branches.length - 1];
+    lastBranch.targetNodeId = targetNodeId;
+    return this;
+  }
+  response(fn) {
+    this._responseFn = fn;
+    return this;
+  }
+  fallback(textOrFn) {
+    this._fallbackText = textOrFn;
+    return this;
+  }
+  retries(n) {
+    this._maxRetries = n;
+    return this;
+  }
+  onMaxRetries(fn) {
+    this._onMaxRetriesFn = fn;
+    return this;
+  }
+  onEnter(fn) {
+    this._onEnter = fn;
+    return this;
+  }
+  onExit(fn) {
+    this._onExit = fn;
+    return this;
+  }
+  ignoreGlobals(ignore = true) {
+    this._ignoreGlobals = ignore;
+    return this;
+  }
+  ask(text) {
+    return this.bot.ask(text);
+  }
+  action(id, options) {
+    return this.bot.action(id, options);
+  }
+  handoff(id, options) {
+    return this.bot.handoff(id, options);
+  }
+  global(matcher, options) {
+    return this.bot.global(matcher, options);
+  }
+  getBranches() {
+    return this._branches;
+  }
+  getResponseFn() {
+    return this._responseFn;
+  }
+  getFallbackText() {
+    return this._fallbackText;
+  }
+  getMaxRetries() {
+    return this._maxRetries;
+  }
+  getOnMaxRetriesFn() {
+    return this._onMaxRetriesFn;
+  }
+  getOnEnterFn() {
+    return this._onEnter;
+  }
+  getOnExitFn() {
+    return this._onExit;
+  }
+  getIgnoreGlobals() {
+    return this._ignoreGlobals;
+  }
+};
+var Bot = class {
+  constructor(flowId, version = 1) {
+    this.flowId = flowId;
+    this.version = version;
+    this.builders = [];
+    this.actionBuilders = [];
+    this.handoffBuilders = [];
+    this.globalBuilders = [];
+  }
+  ask(text) {
+    const defaultId = `node_${this.builders.length}`;
+    const builder = new FlowNodeBuilder(this, defaultId, text);
+    this.builders.push(builder);
+    return builder;
+  }
+  action(id, options) {
+    const builder = new ActionNodeBuilder(this, id, options);
+    this.actionBuilders.push(builder);
+    return builder;
+  }
+  handoff(id, options) {
+    const builder = new HandoffNodeBuilder(this, id, options);
+    this.handoffBuilders.push(builder);
+    return builder;
+  }
+  global(matcher, options) {
+    const builder = new GlobalTransitionBuilder(this, matcher, options);
+    this.globalBuilders.push(builder);
+    return builder;
+  }
+  escalate(ctx) {
+    ctx.set("escalated", true);
+  }
+  compile() {
+    const idSet = /* @__PURE__ */ new Set();
+    const knownNodeIds = [];
+    for (const builder of this.builders) {
+      const nodeId = builder.getId();
+      if (idSet.has(nodeId)) {
+        throw new CompileError(`Duplicate node id "${nodeId}".`);
+      }
+      idSet.add(nodeId);
+      knownNodeIds.push(nodeId);
+    }
+    for (const ab of this.actionBuilders) {
+      const nodeId = ab.getId();
+      if (idSet.has(nodeId)) {
+        throw new CompileError(`Duplicate node id "${nodeId}".`);
+      }
+      idSet.add(nodeId);
+      knownNodeIds.push(nodeId);
+    }
+    for (const hb of this.handoffBuilders) {
+      const nodeId = hb.getId();
+      if (idSet.has(nodeId)) {
+        throw new CompileError(`Duplicate node id "${nodeId}".`);
+      }
+      idSet.add(nodeId);
+      knownNodeIds.push(nodeId);
+    }
+    const globalIdSet = /* @__PURE__ */ new Set();
+    const globals = this.globalBuilders.map((gBuilder, idx) => {
+      const gId = gBuilder.getId(`global_${idx}`);
+      if (globalIdSet.has(gId)) {
+        throw new CompileError(`Duplicate global transition id "${gId}".`);
+      }
+      globalIdSet.add(gId);
+      const targetId = gBuilder.getTargetNodeId();
+      if (!targetId) {
+        throw new CompileError(
+          `Global transition "${gId}" for pattern(s) [${gBuilder.getPatterns().join(", ")}] is missing an explicit .then() target.`
+        );
+      }
+      if (!idSet.has(targetId)) {
+        throw new CompileError(
+          `Unknown node "${targetId}" referenced by global transition "${gId}". Known node IDs: ${knownNodeIds.join(", ")}.`
+        );
+      }
+      const branchMatcher = gBuilder.getMatcher() ?? matchesAny(gBuilder.getPatterns(), gBuilder.getOpts());
+      return {
+        id: gId,
+        matcher: branchMatcher,
+        patterns: gBuilder.getPatterns(),
+        targetNodeId: targetId,
+        priority: gBuilder.getPriority(),
+        responseFn: gBuilder.getResponseFn()
+      };
+    });
+    const nodes = this.builders.map((builder, idx) => {
+      const branches = builder.getBranches();
+      if (branches.length === 0) {
+        throw new CompileError(`Node "${builder.getId()}" is missing an expect() matcher`);
+      }
+      if (branches.length > 1) {
+        for (const branch of branches) {
+          if (!branch.targetNodeId) {
+            throw new CompileError(
+              `branch for pattern(s) [${branch.patterns.join(", ")}] is missing an explicit .then() target \u2014 required once a node has multiple branches`
+            );
+          }
+        }
+      }
+      const defaultNextNodeId = idx < this.builders.length - 1 ? knownNodeIds[idx + 1] : void 0;
+      const allPatterns = [];
+      const transitions = [];
+      const nonWildcardMatchers = [];
+      const wildcardMatchers = [];
+      for (const branch of branches) {
+        let targetId = branch.targetNodeId;
+        if (!targetId && branches.length === 1 && defaultNextNodeId) {
+          targetId = defaultNextNodeId;
+        }
+        if (targetId) {
+          if (!idSet.has(targetId)) {
+            throw new CompileError(
+              `Unknown node "${targetId}" referenced by transition from node "${builder.getId()}". Known node IDs: ${knownNodeIds.join(", ")}.`
+            );
+          }
+        }
+        allPatterns.push(...branch.patterns);
+        transitions.push({
+          targetNodeId: targetId ?? "",
+          patterns: branch.patterns
+        });
+        const branchMatcher = branch.matcher ?? matchesAny(branch.patterns, branch.opts);
+        if (branch.patterns.includes("*")) {
+          wildcardMatchers.push(branchMatcher);
+        } else {
+          nonWildcardMatchers.push(branchMatcher);
+        }
+      }
+      const compositeMatcher = {
+        patterns: allPatterns,
+        normalize: (t) => t.trim().toLowerCase(),
+        match: (inboundText) => {
+          for (const m of nonWildcardMatchers) {
+            const res = m.match(inboundText);
+            if (res.matched) {
+              return res;
+            }
+          }
+          for (const m of wildcardMatchers) {
+            const res = m.match(inboundText);
+            if (res.matched) {
+              return res;
+            }
+          }
+          return { matched: false, pattern: "", confidence: 0 };
+        }
+      };
+      return {
+        id: builder.getId(),
+        text: builder.text,
+        matcher: compositeMatcher,
+        transitions,
+        fallbackText: builder.getFallbackText(),
+        maxRetries: builder.getMaxRetries(),
+        onMaxRetriesFn: builder.getOnMaxRetriesFn(),
+        responseFn: builder.getResponseFn(),
+        onEnter: builder.getOnEnterFn(),
+        onExit: builder.getOnExitFn(),
+        ignoreGlobals: builder.getIgnoreGlobals()
+      };
+    });
+    const actionNodes = this.actionBuilders.map((ab) => {
+      const actionFn = ab.getActionFn();
+      if (!actionFn) {
+        throw new CompileError(`Action node "${ab.getId()}" is missing an execute() handler.`);
+      }
+      const onSuccess = ab.getOnSuccess();
+      const onFailure = ab.getOnFailure();
+      const onTimeout = ab.getOnTimeout();
+      if (!onSuccess && !onFailure) {
+        throw new CompileError(
+          `Action node "${ab.getId()}" must define at least an onSuccess or onFailure transition target.`
+        );
+      }
+      if (onSuccess && !idSet.has(onSuccess.targetNodeId)) {
+        throw new CompileError(
+          `Unknown node "${onSuccess.targetNodeId}" referenced by onSuccess transition on action node "${ab.getId()}". Known node IDs: ${knownNodeIds.join(", ")}.`
+        );
+      }
+      if (onFailure && !idSet.has(onFailure.targetNodeId)) {
+        throw new CompileError(
+          `Unknown node "${onFailure.targetNodeId}" referenced by onFailure transition on action node "${ab.getId()}". Known node IDs: ${knownNodeIds.join(", ")}.`
+        );
+      }
+      if (onTimeout && !idSet.has(onTimeout.targetNodeId)) {
+        throw new CompileError(
+          `Unknown node "${onTimeout.targetNodeId}" referenced by onTimeout transition on action node "${ab.getId()}". Known node IDs: ${knownNodeIds.join(", ")}.`
+        );
+      }
+      const transitions = [];
+      if (onSuccess) transitions.push({ targetNodeId: onSuccess.targetNodeId, patterns: ["success"] });
+      if (onFailure) transitions.push({ targetNodeId: onFailure.targetNodeId, patterns: ["failure"] });
+      if (onTimeout) transitions.push({ targetNodeId: onTimeout.targetNodeId, patterns: ["timeout"] });
+      return {
+        id: ab.getId(),
+        text: ab.getText(),
+        matcher: {
+          patterns: ["*"],
+          normalize: (t) => t,
+          match: () => ({ matched: true, pattern: "*", confidence: 1 })
+        },
+        transitions,
+        fallbackText: "",
+        maxRetries: 0,
+        onEnter: ab.getOnEnterFn(),
+        onExit: ab.getOnExitFn(),
+        isAction: true,
+        action: {
+          execute: actionFn,
+          timeoutMs: ab.getTimeoutMs(),
+          onSuccess,
+          onFailure,
+          onTimeout
+        }
+      };
+    });
+    const allNodes = [...nodes, ...actionNodes];
+    const handoffNodes = this.handoffBuilders.map((hb) => {
+      const resumeId = hb.getResumeNodeId();
+      const fallbackId = hb.getFallbackNodeId();
+      if (resumeId && !idSet.has(resumeId)) {
+        throw new CompileError(
+          `Unknown node "${resumeId}" referenced by resumeAt on handoff node "${hb.getId()}". Known node IDs: ${knownNodeIds.join(", ")}.`
+        );
+      }
+      if (fallbackId && !idSet.has(fallbackId)) {
+        throw new CompileError(
+          `Unknown node "${fallbackId}" referenced by fallbackTo on handoff node "${hb.getId()}". Known node IDs: ${knownNodeIds.join(", ")}.`
+        );
+      }
+      const transitions = [];
+      if (resumeId) transitions.push({ targetNodeId: resumeId, patterns: ["resume"] });
+      if (fallbackId) transitions.push({ targetNodeId: fallbackId, patterns: ["timeout"] });
+      return {
+        id: hb.getId(),
+        text: hb.getText(),
+        matcher: {
+          patterns: ["*"],
+          normalize: (t) => t,
+          match: () => ({ matched: true, pattern: "*", confidence: 1 })
+        },
+        transitions,
+        fallbackText: "",
+        maxRetries: 0,
+        onEnter: hb.getOnEnterFn(),
+        onExit: hb.getOnExitFn(),
+        ignoreGlobals: hb.getIgnoreGlobals(),
+        isHandoff: true,
+        handoff: {
+          reason: hb.getReason(),
+          timeoutMs: hb.getTimeoutMs(),
+          resumeNodeId: resumeId,
+          fallbackNodeId: fallbackId,
+          queueMessage: hb.getQueueMessage(),
+          metadata: hb.getMetadata()
+        }
+      };
+    });
+    const finalNodes = [...allNodes, ...handoffNodes];
+    return {
+      flowId: this.flowId,
+      version: this.version,
+      nodes: finalNodes,
+      globals: globals.length > 0 ? globals : void 0
+    };
+  }
+};
+
+// core/context.ts
+var Context = class {
+  constructor(initialData = {}) {
+    this.data = initialData;
+  }
+  set(key, value) {
+    this.data[key] = value;
+  }
+  get(key) {
+    return this.data[key];
+  }
+  has(key) {
+    return Object.prototype.hasOwnProperty.call(this.data, key);
+  }
+  delete(key) {
+    delete this.data[key];
+  }
+  clear() {
+    this.data = {};
+  }
+  all() {
+    return { ...this.data };
+  }
+};
+
+// core/fsm.ts
+async function runWithTimeout(fn, timeoutMs = 5e3) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error("Handler execution timed out"));
+    }, timeoutMs);
+    Promise.resolve(fn()).then((val) => {
+      clearTimeout(timer);
+      resolve(val);
+    }).catch((err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+var FSMEngine = class {
+  constructor(flow) {
+    this.flow = flow;
+  }
+  createInitialState(waUserId) {
+    return {
+      waUserId,
+      flowId: this.flow.flowId,
+      flowVersion: this.flow.version,
+      currentNodeId: this.flow.nodes[0]?.id || "",
+      context: {},
+      retryCount: 0,
+      status: "active"
+    };
+  }
+  async executeInitialEnter(state) {
+    if (state.status !== "active") return state;
+    const node = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+    if (node && node.onEnter) {
+      const ctx = new Context({ ...state.context });
+      await this.safelyExecuteHook(
+        node.onEnter,
+        ctx,
+        { fromNodeId: void 0, toNodeId: node.id, isInitial: true },
+        `onEnter (initial) on node "${node.id}"`
+      );
+      return {
+        ...state,
+        context: ctx.all()
+      };
+    }
+    return state;
+  }
+  async executeActionNode(state) {
+    const node = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+    if (!node || !node.isAction) {
+      return {
+        nextState: state,
+        outboundText: null
+      };
+    }
+    const ctx = new Context({ ...state.context });
+    return await this.resolveDestination(state, node, node.id, "", ctx);
+  }
+  isGlobalIgnored(node, global) {
+    if (node.ignoreGlobals === true) {
+      return true;
+    }
+    if (Array.isArray(node.ignoreGlobals)) {
+      const ignoredList = node.ignoreGlobals;
+      if (ignoredList.includes(global.id)) {
+        return true;
+      }
+      if (global.patterns && global.patterns.some((p) => ignoredList.includes(p))) {
+        return true;
+      }
+    }
+    return false;
+  }
+  async safelyExecuteHook(hook, ctx, info, hookName) {
+    if (!hook) return;
+    try {
+      await runWithTimeout(() => hook(ctx, info));
+    } catch (err) {
+      console.error(`[FSMEngine] ${hookName} hook failed or timed out:`, err);
+    }
+  }
+  async resolveDestination(state, sourceNode, targetNodeId, triggerText, ctx, matchedGlobalId, depth = 0) {
+    if (depth > 10) {
+      console.error(`[FSMEngine] Maximum action chaining depth exceeded (depth > 10). Breaking loop.`);
+      return {
+        nextState: {
+          ...state,
+          context: ctx.all(),
+          status: "escalated"
+        },
+        outboundText: "An unexpected error occurred. Connecting you with an agent."
+      };
+    }
+    const targetNode = this.flow.nodes.find((n) => n.id === targetNodeId);
+    if (!targetNode) {
+      const nextState2 = {
+        ...state,
+        context: ctx.all(),
+        status: "completed"
+      };
+      return {
+        nextState: nextState2,
+        outboundText: null,
+        matchedGlobalId
+      };
+    }
+    await this.safelyExecuteHook(
+      targetNode.onEnter,
+      ctx,
+      { fromNodeId: sourceNode.id, toNodeId: targetNode.id, triggerText, isInitial: false },
+      `onEnter on node "${targetNode.id}"`
+    );
+    if (targetNode.isAction && targetNode.action) {
+      const actionDef = targetNode.action;
+      const timeoutMs = actionDef.timeoutMs ?? 5e3;
+      let actionSuccess = false;
+      let actionResult = null;
+      let actionTimedOut = false;
+      let actionError = null;
+      try {
+        actionResult = await runWithTimeout(() => actionDef.execute(ctx), timeoutMs);
+        actionSuccess = true;
+      } catch (err) {
+        if (err?.message?.includes("timed out")) {
+          actionTimedOut = true;
+        }
+        actionError = err;
+      }
+      if (actionSuccess) {
+        if (actionDef.onSuccess?.handler) {
+          try {
+            await runWithTimeout(() => actionDef.onSuccess.handler(actionResult, ctx), timeoutMs);
+          } catch (err) {
+            console.error(`[FSMEngine] onSuccess handler on action node "${targetNode.id}" failed:`, err);
+          }
+        }
+        const nextTargetId = actionDef.onSuccess?.targetNodeId;
+        await this.safelyExecuteHook(
+          targetNode.onExit,
+          ctx,
+          { fromNodeId: targetNode.id, toNodeId: nextTargetId, triggerText },
+          `onExit on action node "${targetNode.id}"`
+        );
+        if (nextTargetId) {
+          return await this.resolveDestination(state, targetNode, nextTargetId, triggerText, ctx, matchedGlobalId, depth + 1);
+        } else {
+          return {
+            nextState: { ...state, context: ctx.all(), status: "completed" },
+            outboundText: null,
+            matchedGlobalId
+          };
+        }
+      } else if (actionTimedOut) {
+        const timeoutBranch = actionDef.onTimeout ?? actionDef.onFailure;
+        if (timeoutBranch?.handler) {
+          try {
+            await runWithTimeout(() => timeoutBranch.handler(actionError, ctx), timeoutMs);
+          } catch (err) {
+            console.error(`[FSMEngine] onTimeout handler on action node "${targetNode.id}" failed:`, err);
+          }
+        }
+        const nextTargetId = timeoutBranch?.targetNodeId;
+        await this.safelyExecuteHook(
+          targetNode.onExit,
+          ctx,
+          { fromNodeId: targetNode.id, toNodeId: nextTargetId, triggerText },
+          `onExit on action node "${targetNode.id}"`
+        );
+        if (nextTargetId) {
+          return await this.resolveDestination(state, targetNode, nextTargetId, triggerText, ctx, matchedGlobalId, depth + 1);
+        } else {
+          return {
+            nextState: { ...state, context: ctx.all(), status: "completed" },
+            outboundText: null,
+            matchedGlobalId
+          };
+        }
+      } else {
+        const failureBranch = actionDef.onFailure;
+        if (failureBranch?.handler) {
+          try {
+            await runWithTimeout(() => failureBranch.handler(actionError, ctx), timeoutMs);
+          } catch (err) {
+            console.error(`[FSMEngine] onFailure handler on action node "${targetNode.id}" failed:`, err);
+          }
+        }
+        const nextTargetId = failureBranch?.targetNodeId;
+        await this.safelyExecuteHook(
+          targetNode.onExit,
+          ctx,
+          { fromNodeId: targetNode.id, toNodeId: nextTargetId, triggerText },
+          `onExit on action node "${targetNode.id}"`
+        );
+        if (nextTargetId) {
+          return await this.resolveDestination(state, targetNode, nextTargetId, triggerText, ctx, matchedGlobalId, depth + 1);
+        } else {
+          return {
+            nextState: { ...state, context: ctx.all(), status: "completed" },
+            outboundText: null,
+            matchedGlobalId
+          };
+        }
+      }
+    }
+    if (targetNode.isHandoff) {
+      const handoffDef = targetNode.handoff;
+      const handoffSession = {
+        state: "pending",
+        reason: handoffDef?.reason,
+        requestedAt: Date.now(),
+        resumeNodeId: handoffDef?.resumeNodeId,
+        fallbackNodeId: handoffDef?.fallbackNodeId,
+        timeoutMs: handoffDef?.timeoutMs ?? 10 * 60 * 1e3,
+        queueMessage: handoffDef?.queueMessage,
+        metadata: handoffDef?.metadata ? { ...handoffDef.metadata } : void 0
+      };
+      const nextState2 = {
+        ...state,
+        currentNodeId: targetNode.id,
+        retryCount: 0,
+        context: ctx.all(),
+        status: "handoff",
+        handoff: handoffSession
+      };
+      return {
+        nextState: nextState2,
+        outboundText: targetNode.text,
+        matchedGlobalId
+      };
+    }
+    const nextState = {
+      ...state,
+      currentNodeId: targetNode.id,
+      retryCount: 0,
+      context: ctx.all(),
+      status: "active"
+    };
+    return {
+      nextState,
+      outboundText: targetNode.text,
+      matchedGlobalId
+    };
+  }
+  async executeGlobalTransition(state, node, global, matchedPattern, inboundText, ctx) {
+    if (global.responseFn) {
+      try {
+        await runWithTimeout(
+          () => global.responseFn({ raw: inboundText, pattern: matchedPattern }, ctx)
+        );
+      } catch (err) {
+        console.error(`[FSMEngine] Global response handler for "${global.id}" failed or timed out:`, err);
+      }
+    }
+    await this.safelyExecuteHook(
+      node.onExit,
+      ctx,
+      { fromNodeId: node.id, toNodeId: global.targetNodeId, triggerText: inboundText },
+      `onExit on node "${node.id}"`
+    );
+    return await this.resolveDestination(state, node, global.targetNodeId, inboundText, ctx, global.id);
+  }
+  async transition(state, inboundText) {
+    if (state.status === "completed" || state.status === "escalated" || state.status === "abandoned") {
+      return {
+        nextState: state,
+        outboundText: null
+      };
+    }
+    if (state.status === "handoff") {
+      const node2 = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+      if (!node2) {
+        return {
+          nextState: state,
+          outboundText: null
+        };
+      }
+      const ctx2 = new Context({ ...state.context });
+      const allGlobals2 = this.flow.globals ?? [];
+      const activeGlobals2 = allGlobals2.filter((g) => !this.isGlobalIgnored(node2, g));
+      for (const g of activeGlobals2.filter((g2) => g2.priority === "high")) {
+        let gMatch;
+        try {
+          gMatch = g.matcher.match(inboundText);
+        } catch {
+          gMatch = { matched: false, pattern: "", confidence: 0 };
+        }
+        if (gMatch.matched) {
+          const resolvedHandoff = state.handoff ? {
+            ...state.handoff,
+            state: "resolved",
+            resolvedAt: Date.now()
+          } : void 0;
+          const stateWithResolvedHandoff = {
+            ...state,
+            status: "active",
+            handoff: resolvedHandoff
+          };
+          return await this.executeGlobalTransition(
+            stateWithResolvedHandoff,
+            node2,
+            g,
+            gMatch.pattern,
+            inboundText,
+            ctx2
+          );
+        }
+      }
+      for (const g of activeGlobals2.filter((g2) => g2.priority === "low")) {
+        let gMatch;
+        try {
+          gMatch = g.matcher.match(inboundText);
+        } catch {
+          gMatch = { matched: false, pattern: "", confidence: 0 };
+        }
+        if (gMatch.matched) {
+          const resolvedHandoff = state.handoff ? {
+            ...state.handoff,
+            state: "resolved",
+            resolvedAt: Date.now()
+          } : void 0;
+          const stateWithResolvedHandoff = {
+            ...state,
+            status: "active",
+            handoff: resolvedHandoff
+          };
+          return await this.executeGlobalTransition(
+            stateWithResolvedHandoff,
+            node2,
+            g,
+            gMatch.pattern,
+            inboundText,
+            ctx2
+          );
+        }
+      }
+      if (state.handoff?.state === "pending") {
+        const queueMsg = state.handoff.queueMessage !== void 0 ? state.handoff.queueMessage : "You are in the queue. An agent will be with you shortly.";
+        return {
+          nextState: state,
+          outboundText: queueMsg
+        };
+      }
+      return {
+        nextState: state,
+        outboundText: null
+      };
+    }
+    const node = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+    if (!node) {
+      return {
+        nextState: state,
+        outboundText: null
+      };
+    }
+    const ctx = new Context({ ...state.context });
+    const allGlobals = this.flow.globals ?? [];
+    const activeGlobals = allGlobals.filter((g) => !this.isGlobalIgnored(node, g));
+    const highPriorityGlobals = activeGlobals.filter((g) => g.priority === "high");
+    const lowPriorityGlobals = activeGlobals.filter((g) => g.priority === "low");
+    for (const g of highPriorityGlobals) {
+      let gMatch;
+      try {
+        gMatch = g.matcher.match(inboundText);
+      } catch (err) {
+        console.error(`[FSMEngine] Global matcher "${g.id}" threw:`, err);
+        gMatch = { matched: false, pattern: "", confidence: 0 };
+      }
+      if (gMatch.matched) {
+        return await this.executeGlobalTransition(state, node, g, gMatch.pattern, inboundText, ctx);
+      }
+    }
+    let matchResult;
+    try {
+      matchResult = node.matcher.match(inboundText);
+    } catch (err) {
+      console.error("Matcher threw an error:", err);
+      matchResult = { matched: false, pattern: "", confidence: 0 };
+    }
+    if (matchResult.matched) {
+      let handlerSucceeded = true;
+      if (node.responseFn) {
+        try {
+          await runWithTimeout(() => node.responseFn({ raw: inboundText, pattern: matchResult.pattern }, ctx));
+        } catch (err) {
+          console.error("Response handler failed or timed out:", err);
+          handlerSucceeded = false;
+        }
+      }
+      if (handlerSucceeded) {
+        let selectedTransition = node.transitions[0];
+        if (node.transitions.length > 1) {
+          if (matchResult.pattern !== "*") {
+            const exactBranch = node.transitions.find(
+              (t) => t.patterns && t.patterns.includes(matchResult.pattern)
+            );
+            if (exactBranch) {
+              selectedTransition = exactBranch;
+            } else {
+              const wildcardBranch = node.transitions.find(
+                (t) => t.patterns && t.patterns.includes("*")
+              );
+              if (wildcardBranch) {
+                selectedTransition = wildcardBranch;
+              }
+            }
+          } else {
+            const wildcardBranch = node.transitions.find(
+              (t) => t.patterns && t.patterns.includes("*")
+            );
+            if (wildcardBranch) {
+              selectedTransition = wildcardBranch;
+            }
+          }
+        }
+        const nextNodeId = selectedTransition?.targetNodeId;
+        await this.safelyExecuteHook(
+          node.onExit,
+          ctx,
+          { fromNodeId: node.id, toNodeId: nextNodeId || void 0, triggerText: inboundText },
+          `onExit on node "${node.id}"`
+        );
+        if (nextNodeId) {
+          return await this.resolveDestination(state, node, nextNodeId, inboundText, ctx);
+        } else {
+          const nextState = {
+            ...state,
+            context: ctx.all(),
+            status: "completed"
+          };
+          return {
+            nextState,
+            outboundText: null
+          };
+        }
+      }
+    }
+    for (const g of lowPriorityGlobals) {
+      let gMatch;
+      try {
+        gMatch = g.matcher.match(inboundText);
+      } catch (err) {
+        console.error(`[FSMEngine] Global matcher "${g.id}" threw:`, err);
+        gMatch = { matched: false, pattern: "", confidence: 0 };
+      }
+      if (gMatch.matched) {
+        return await this.executeGlobalTransition(state, node, g, gMatch.pattern, inboundText, ctx);
+      }
+    }
+    return this.handleFallback(state, node, ctx);
+  }
+  async handleFallback(state, node, ctx) {
+    const nextRetryCount = state.retryCount + 1;
+    if (nextRetryCount <= node.maxRetries) {
+      let fallbackMessage = "Please try again.";
+      if (typeof node.fallbackText === "function") {
+        try {
+          const res = await runWithTimeout(() => node.fallbackText(ctx));
+          if (typeof res === "string") {
+            fallbackMessage = res;
+          }
+        } catch (err) {
+          console.error("Fallback generator function failed or timed out:", err);
+        }
+      } else if (typeof node.fallbackText === "string") {
+        fallbackMessage = node.fallbackText;
+      }
+      const nextState = {
+        ...state,
+        retryCount: nextRetryCount,
+        context: ctx.all()
+      };
+      return {
+        nextState,
+        outboundText: fallbackMessage
+      };
+    } else {
+      let escalationMessage = "Let me connect you with a human \u2014 someone will be with you shortly.";
+      if (node.onMaxRetriesFn) {
+        try {
+          const res = await runWithTimeout(() => node.onMaxRetriesFn(ctx));
+          if (typeof res === "string") {
+            escalationMessage = res;
+          }
+        } catch (err) {
+          console.error("onMaxRetries handler failed or timed out:", err);
+        }
+      }
+      const nextState = {
+        ...state,
+        retryCount: nextRetryCount,
+        context: ctx.all(),
+        status: "escalated"
+      };
+      return {
+        nextState,
+        outboundText: escalationMessage
+      };
+    }
+  }
+  connectAgent(state, agentId, metadata) {
+    if (state.status !== "handoff" || !state.handoff) {
+      throw new Error(`Cannot connect agent: state status is "${state.status}", not "handoff".`);
+    }
+    const updatedHandoff = {
+      ...state.handoff,
+      state: "connected",
+      assignedAgentId: agentId,
+      connectedAt: Date.now(),
+      metadata: metadata ? { ...state.handoff.metadata, ...metadata } : state.handoff.metadata
+    };
+    return {
+      ...state,
+      handoff: updatedHandoff
+    };
+  }
+  async resolveHandoff(state, options) {
+    if (state.status !== "handoff" || !state.handoff) {
+      throw new Error(`Cannot resolve handoff: state status is "${state.status}", not "handoff".`);
+    }
+    const currentNode = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+    const ctx = new Context({ ...state.context, ...options?.contextUpdates || {} });
+    if (options?.resolutionNotes) {
+      ctx.set("handoff_resolution_notes", options.resolutionNotes);
+    }
+    const targetResumeId = options?.resumeNodeId ?? state.handoff.resumeNodeId;
+    if (currentNode) {
+      await this.safelyExecuteHook(
+        currentNode.onExit,
+        ctx,
+        {
+          fromNodeId: currentNode.id,
+          toNodeId: targetResumeId,
+          triggerText: "agent_resolve"
+        },
+        `onExit on handoff node "${currentNode.id}"`
+      );
+    }
+    const resolvedSession = {
+      ...state.handoff,
+      state: "resolved",
+      resolvedAt: Date.now()
+    };
+    const resolvedState = {
+      ...state,
+      status: "active",
+      context: ctx.all(),
+      handoff: resolvedSession
+    };
+    if (targetResumeId) {
+      return await this.resolveDestination(
+        resolvedState,
+        currentNode ?? { id: state.currentNodeId },
+        targetResumeId,
+        "agent_resolve",
+        ctx
+      );
+    } else {
+      return {
+        nextState: {
+          ...resolvedState,
+          status: "completed"
+        },
+        outboundText: null
+      };
+    }
+  }
+  async checkHandoffTimeout(state, currentTime = Date.now()) {
+    if (state.status !== "handoff" || !state.handoff || state.handoff.state !== "pending") {
+      return null;
+    }
+    const timeoutLimit = state.handoff.timeoutMs ?? 10 * 60 * 1e3;
+    if (currentTime - state.handoff.requestedAt < timeoutLimit) {
+      return null;
+    }
+    const currentNode = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+    const ctx = new Context({ ...state.context });
+    const timedOutSession = {
+      ...state.handoff,
+      state: "timed_out"
+    };
+    const fallbackTargetId = state.handoff.fallbackNodeId;
+    if (currentNode) {
+      await this.safelyExecuteHook(
+        currentNode.onExit,
+        ctx,
+        {
+          fromNodeId: currentNode.id,
+          toNodeId: fallbackTargetId,
+          triggerText: "handoff_timeout"
+        },
+        `onExit on handoff node "${currentNode.id}"`
+      );
+    }
+    const timedOutState = {
+      ...state,
+      status: "active",
+      context: ctx.all(),
+      handoff: timedOutSession
+    };
+    if (fallbackTargetId) {
+      return await this.resolveDestination(
+        timedOutState,
+        currentNode ?? { id: state.currentNodeId },
+        fallbackTargetId,
+        "handoff_timeout",
+        ctx
+      );
+    } else {
+      return {
+        nextState: {
+          ...timedOutState,
+          status: "escalated"
+        },
+        outboundText: "Live agent request timed out. Please try again later or reach out via email."
+      };
+    }
+  }
+  getAvailableCommands(state) {
+    const currentNode = this.flow.nodes.find((n) => n.id === state.currentNodeId);
+    const commands = [];
+    if (state.status === "completed" || state.status === "escalated" || state.status === "abandoned") {
+      return {
+        currentNodeId: state.currentNodeId,
+        status: state.status,
+        handoffState: state.handoff?.state,
+        commands: []
+      };
+    }
+    if (currentNode && this.flow.globals) {
+      for (const g of this.flow.globals) {
+        if (!this.isGlobalIgnored(currentNode, g)) {
+          for (const p of g.patterns || [g.id]) {
+            commands.push({
+              kind: "global",
+              command: p,
+              targetNodeId: g.targetNodeId,
+              description: `Global interrupt to "${g.targetNodeId}"`
+            });
+          }
+        }
+      }
+    }
+    if (state.status === "handoff") {
+      if (state.handoff?.state === "pending") {
+        commands.push({
+          kind: "handoff",
+          command: "agent:connect",
+          description: "Connect available human agent"
+        });
+        commands.push({
+          kind: "handoff",
+          command: "agent:timeout",
+          targetNodeId: state.handoff?.fallbackNodeId,
+          description: "Trigger handoff timeout fallback"
+        });
+      } else if (state.handoff?.state === "connected") {
+        commands.push({
+          kind: "handoff",
+          command: "agent:resolve",
+          targetNodeId: state.handoff?.resumeNodeId,
+          description: "Resolve live session and resume bot flow"
+        });
+      }
+      return {
+        currentNodeId: state.currentNodeId,
+        status: state.status,
+        handoffState: state.handoff?.state,
+        commands
+      };
+    }
+    if (currentNode) {
+      if (currentNode.isAction) {
+        commands.push({
+          kind: "action",
+          command: "action:execute",
+          targetNodeId: currentNode.action?.onSuccess?.targetNodeId,
+          description: "Execute async action handler"
+        });
+      } else {
+        for (const t of currentNode.transitions) {
+          for (const p of t.patterns || ["*"]) {
+            commands.push({
+              kind: "local",
+              command: p,
+              targetNodeId: t.targetNodeId,
+              description: `Transition to "${t.targetNodeId}"`
+            });
+          }
+        }
+      }
+    }
+    return {
+      currentNodeId: state.currentNodeId,
+      status: state.status,
+      handoffState: state.handoff?.state,
+      commands
+    };
+  }
+  getLegalTransitions(state) {
+    return this.getAvailableCommands(state);
+  }
+};
+async function runConversationStep(waUserId, messageText, options) {
+  const fsm = new FSMEngine(options.flow);
+  let state = await options.persistence.load(waUserId);
+  if (!state) {
+    state = fsm.createInitialState(waUserId);
+    state = await fsm.executeInitialEnter(state);
+  }
+  const result = await fsm.transition(state, messageText);
+  await options.persistence.save(result.nextState);
+  return {
+    nextState: result.nextState,
+    result
+  };
+}
+
+// persistence/persistence.ts
+import mongoose, { Schema } from "mongoose";
+var OptimisticConcurrencyError = class extends Error {
+  constructor(waUserId, expectedVersion) {
+    super(`Optimistic concurrency violation for user ${waUserId}. Expected version: ${expectedVersion}`);
+    this.waUserId = waUserId;
+    this.expectedVersion = expectedVersion;
+    this.name = "OptimisticConcurrencyError";
+  }
+};
+var compiledRegistry = /* @__PURE__ */ new Map();
+function registerFlowDefinition(flow) {
+  const key = `${flow.flowId}:${flow.version}`;
+  compiledRegistry.set(key, flow);
+}
+var ConversationStateSchema = new Schema({
+  waUserId: { type: String, required: true, unique: true, index: true },
+  flowId: { type: String, required: true },
+  flowVersion: { type: Number, required: true },
+  currentNodeId: { type: String, required: true },
+  context: { type: Schema.Types.Mixed, default: {} },
+  retryCount: { type: Number, required: true, default: 0 },
+  status: { type: String, required: true, enum: ["active", "escalated", "completed", "abandoned", "handoff"], default: "active" },
+  handoff: { type: Schema.Types.Mixed },
+  version: { type: Number, required: true, default: 0 }
+});
+var FlowNodeSchema = new Schema({
+  id: { type: String, required: true },
+  text: { type: String, required: true },
+  patterns: [{ type: String }],
+  fallbackText: { type: Schema.Types.Mixed },
+  maxRetries: { type: Number, required: true }
+});
+var FlowDefinitionSchema = new Schema({
+  flowId: { type: String, required: true },
+  version: { type: Number, required: true },
+  nodes: [FlowNodeSchema]
+});
+FlowDefinitionSchema.index({ flowId: 1, version: 1 }, { unique: true });
+var MongoosePersistenceAdapter = class {
+  constructor(connection = mongoose.connection) {
+    this.ConversationStateModel = connection.models.ConversationState || connection.model("ConversationState", ConversationStateSchema);
+    this.FlowDefinitionModel = connection.models.FlowDefinition || connection.model("FlowDefinition", FlowDefinitionSchema);
+  }
+  async load(waUserId) {
+    const doc = await this.ConversationStateModel.findOne({ waUserId });
+    if (!doc) return null;
+    return {
+      waUserId: doc.waUserId,
+      flowId: doc.flowId,
+      flowVersion: doc.flowVersion,
+      currentNodeId: doc.currentNodeId,
+      context: doc.context instanceof Map ? Object.fromEntries(doc.context) : doc.context,
+      retryCount: doc.retryCount,
+      status: doc.status,
+      version: doc.version
+    };
+  }
+  async save(state) {
+    const currentVersion = state.version;
+    if (currentVersion === void 0) {
+      try {
+        const doc = new this.ConversationStateModel({
+          waUserId: state.waUserId,
+          flowId: state.flowId,
+          flowVersion: state.flowVersion,
+          currentNodeId: state.currentNodeId,
+          context: state.context,
+          retryCount: state.retryCount,
+          status: state.status,
+          version: 1
+        });
+        await doc.save();
+      } catch (err) {
+        if (err.code === 11e3) {
+          throw new OptimisticConcurrencyError(state.waUserId, 0);
+        }
+        throw err;
+      }
+    } else {
+      const result = await this.ConversationStateModel.updateOne(
+        { waUserId: state.waUserId, version: currentVersion },
+        {
+          $set: {
+            flowId: state.flowId,
+            flowVersion: state.flowVersion,
+            currentNodeId: state.currentNodeId,
+            context: state.context,
+            retryCount: state.retryCount,
+            status: state.status,
+            version: currentVersion + 1
+          }
+        },
+        { runValidators: true }
+      );
+      if (result.matchedCount === 0) {
+        throw new OptimisticConcurrencyError(state.waUserId, currentVersion);
+      }
+    }
+  }
+  async loadFlowDefinition(flowId, version) {
+    const registryKey = `${flowId}:${version}`;
+    const registered = compiledRegistry.get(registryKey);
+    if (registered) {
+      return registered;
+    }
+    throw new Error(
+      `Flow "${flowId}" (v${version}) is not loaded/registered in the in-memory compiledRegistry. Active flows must be registered on application startup by calling registerFlowDefinition() or compiling a flow with bot.compile() to preserve execution callbacks and handlers.`
+    );
+  }
+  async saveFlowDefinition(flow) {
+    registerFlowDefinition(flow);
+    const serializedNodes = flow.nodes.map((n) => ({
+      id: n.id,
+      text: n.text,
+      patterns: n.matcher.patterns,
+      fallbackText: typeof n.fallbackText === "string" ? n.fallbackText : "[Dynamic Handler]",
+      maxRetries: n.maxRetries
+    }));
+    await this.FlowDefinitionModel.updateOne(
+      { flowId: flow.flowId, version: flow.version },
+      {
+        $set: {
+          flowId: flow.flowId,
+          version: flow.version,
+          nodes: serializedNodes
+        }
+      },
+      {
+        upsert: true,
+        runValidators: true
+      }
+    );
+  }
+};
+var CallbackPersistenceAdapter = class {
+  constructor(options) {
+    this.options = options;
+  }
+  async load(waUserId) {
+    return this.options.load(waUserId);
+  }
+  async save(state) {
+    return this.options.save(state);
+  }
+  async loadFlowDefinition(flowId, version) {
+    return this.options.loadFlowDefinition(flowId, version);
+  }
+  async saveFlowDefinition(flow) {
+    return this.options.saveFlowDefinition(flow);
+  }
+};
+
+// core/idempotency.ts
+var IdempotencyService = class {
+  constructor(redis) {
+    this.redis = redis;
+  }
+  /**
+   * Attempts to acquire an idempotency lock on a WhatsApp message ID (wamid).
+   * @param wamid Unique WhatsApp message ID from the webhook payload.
+   * @param ttlSeconds Expiration time in seconds (default: 21600 - 6 hours).
+   * @returns Promise<boolean> True if the lock was acquired (first time), false if it is a duplicate.
+   */
+  async checkAndLock(wamid, ttlSeconds = 21600) {
+    if (!wamid) {
+      throw new Error("wamid is required for idempotency check");
+    }
+    const key = `dedup:${wamid}`;
+    const result = await this.redis.set(key, "1", "EX", ttlSeconds, "NX");
+    return result === "OK";
+  }
+  /**
+   * Releases/deletes the idempotency lock for a message ID.
+   * Useful to roll back locks when downstream operations (e.g. queue enqueue) fail.
+   */
+  async release(wamid) {
+    if (wamid) {
+      const key = `dedup:${wamid}`;
+      await this.redis.del(key);
+    }
+  }
+};
+
+// adapters/flaresend.ts
+import { Flaresend } from "flaresend";
+var FlaresendSendError = class extends Error {
+  constructor(message, isAmbiguous, statusCode, code) {
+    super(message);
+    this.name = "FlaresendSendError";
+    this.isAmbiguous = isAmbiguous;
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+var KnownNotSentError = class extends FlaresendSendError {
+  constructor(message, statusCode, code) {
+    super(message, false, statusCode, code);
+    this.name = "KnownNotSentError";
+  }
+};
+var AmbiguousSendError = class extends FlaresendSendError {
+  constructor(message, statusCode, code) {
+    super(message, true, statusCode, code);
+    this.name = "AmbiguousSendError";
+  }
+};
+function classifyFlaresendError(err) {
+  if (err instanceof FlaresendSendError) {
+    return err;
+  }
+  const message = err?.message || String(err);
+  const status = typeof err?.status === "number" ? err.status : typeof err?.statusCode === "number" ? err.statusCode : typeof err?.response?.status === "number" ? err.response.status : void 0;
+  const code = err?.code || err?.errno;
+  if (status !== void 0 && status >= 400 && status < 500 || code === "ENOTFOUND" || code === "ECONNREFUSED" || code === "EADDRNOTAVAIL") {
+    return new KnownNotSentError(
+      `Flaresend rejected request (Status: ${status ?? "N/A"}, Code: ${code ?? "N/A"}): ${message}`,
+      status,
+      code
+    );
+  }
+  return new AmbiguousSendError(
+    `Unconfirmed delivery status (Status: ${status ?? "N/A"}, Code: ${code ?? "N/A"}): ${message}`,
+    status,
+    code
+  );
+}
+var FlaresendClient = class {
+  constructor(options = {}) {
+    this.sdk = null;
+    this.isMock = !!options.mock;
+    const apiKey = options.apiKey || process.env.FLARESEND_API_KEY || "";
+    if (!this.isMock) {
+      if (!apiKey) {
+        throw new Error(
+          "FlaresendClient: FLARESEND_API_KEY is missing and mock mode is disabled. Provide a valid API key or explicitly set options.mock = true."
+        );
+      }
+      this.sdk = new Flaresend(apiKey, {
+        baseUrl: options.baseUrl
+      });
+    }
+  }
+  /**
+   * Sends an outbound WhatsApp message to the recipient using the official Flaresend SDK.
+   * Categorizes any transmission errors into KnownNotSentError or AmbiguousSendError.
+   */
+  async sendMessage(to, text) {
+    if (this.isMock || !this.sdk) {
+      console.warn(`[FlaresendClient MOCK] Sending message to ${to}: ${text}`);
+      return { success: true, messageId: `mock-fs-${Date.now()}` };
+    }
+    try {
+      const response = await this.sdk.messages.send({
+        recipients: [to],
+        type: "text",
+        text
+      });
+      return {
+        success: response.success,
+        messageId: response.successful_recipients?.[0]
+      };
+    } catch (err) {
+      const classifiedError = classifyFlaresendError(err);
+      if (classifiedError.isAmbiguous) {
+        console.warn(`[AMBIGUOUS_SEND_FAILURE] Flaresend send to ${to} resulted in ambiguous error:`, classifiedError.message);
+      } else {
+        console.error(`[KNOWN_NOT_SENT_FAILURE] Flaresend send to ${to} failed before transmission:`, classifiedError.message);
+      }
+      throw classifiedError;
+    }
+  }
+};
+
+// adapters/webhook.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function extractWebhookPayload(body) {
+  const messages = [];
+  const statuses = [];
+  if (!body) {
+    return { messages, statuses };
+  }
+  if (Array.isArray(body.messages)) {
+    for (const msg of body.messages) {
+      if (msg && msg.id && msg.from) {
+        messages.push({
+          id: msg.id,
+          from: msg.from,
+          text: msg.text?.body || msg.text || "",
+          timestamp: Number(msg.timestamp) || Date.now()
+        });
+      }
+    }
+  }
+  if (Array.isArray(body.statuses)) {
+    for (const st of body.statuses) {
+      if (st && st.id) {
+        statuses.push({
+          id: st.id,
+          status: st.status || "",
+          recipient_id: st.recipient_id || st.recipient || "",
+          timestamp: Number(st.timestamp) || Date.now()
+        });
+      }
+    }
+  }
+  if (Array.isArray(body.entry)) {
+    for (const entry of body.entry) {
+      if (Array.isArray(entry.changes)) {
+        for (const change of entry.changes) {
+          const val = change.value;
+          if (val) {
+            if (Array.isArray(val.messages)) {
+              for (const msg of val.messages) {
+                if (msg && msg.id && msg.from) {
+                  messages.push({
+                    id: msg.id,
+                    from: msg.from,
+                    text: msg.text?.body || msg.text || "",
+                    timestamp: Number(msg.timestamp) || Date.now()
+                  });
+                }
+              }
+            }
+            if (Array.isArray(val.statuses)) {
+              for (const st of val.statuses) {
+                if (st && st.id) {
+                  statuses.push({
+                    id: st.id,
+                    status: st.status || "",
+                    recipient_id: st.recipient_id || st.recipient || "",
+                    timestamp: Number(st.timestamp) || Date.now()
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  return { messages, statuses };
+}
+function validateWebhookCoreOptions(options) {
+  if (!options.webhookSecret && !options.allowUnsigned) {
+    throw new Error(
+      "Webhook security violation: webhookSecret is not configured, and allowUnsigned is not set to true. You must explicitly provide webhookSecret or set allowUnsigned: true to allow unverified payloads."
+    );
+  }
+}
+function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader || !secret) return false;
+  const signature = signatureHeader.startsWith("sha256=") ? signatureHeader.substring(7) : signatureHeader;
+  const hmac = createHmac("sha256", secret);
+  hmac.update(rawBody);
+  const expectedSignature = hmac.digest("hex");
+  try {
+    return timingSafeEqual(
+      Buffer.from(signature, "hex"),
+      Buffer.from(expectedSignature, "hex")
+    );
+  } catch {
+    return false;
+  }
+}
+async function handleWebhookCore(req, options) {
+  validateWebhookCoreOptions(options);
+  const { idempotencyService, queue, webhookSecret } = options;
+  if (webhookSecret && !options.allowUnsigned) {
+    const sigHeader = req.headers["x-hub-signature-256"] || req.headers["x-flaresend-signature"];
+    const rawBody = req.rawBody;
+    if (!rawBody) {
+      throw new Error(
+        "Webhook signature verification failed on configuration: webhookSecret is active, but raw request body capture (e.g. req.rawBody) is missing. Please configure a raw-body capture middleware/plugin to preserve exact wire bytes."
+      );
+    }
+    if (!verifyWebhookSignature(rawBody, sigHeader, webhookSecret)) {
+      return {
+        status: 401,
+        body: { error: "Unauthorized: Invalid webhook signature" }
+      };
+    }
+  }
+  const { messages, statuses } = extractWebhookPayload(req.body);
+  if (messages.length === 0 && statuses.length === 0) {
+    return {
+      status: 400,
+      body: { error: "Bad Request: Invalid payload structure or missing entries" }
+    };
+  }
+  let enqueuedCount = 0;
+  let duplicateCount = 0;
+  for (const msg of messages) {
+    const isNew = await idempotencyService.checkAndLock(msg.id);
+    if (isNew) {
+      try {
+        await queue.add("whatsapp-message", {
+          wamid: msg.id,
+          waUserId: msg.from,
+          messageText: msg.text,
+          timestamp: msg.timestamp
+        });
+        enqueuedCount++;
+      } catch (err) {
+        await idempotencyService.release(msg.id);
+        throw err;
+      }
+    } else {
+      duplicateCount++;
+    }
+  }
+  return {
+    status: 200,
+    body: {
+      status: "success",
+      processed: {
+        enqueuedMessages: enqueuedCount,
+        duplicateMessages: duplicateCount,
+        statusUpdates: statuses.length
+      }
+    }
+  };
+}
+function createFastifyAdapter(options) {
+  validateWebhookCoreOptions(options);
+  return async (request, reply) => {
+    let rawBody = request.rawBody;
+    if (Buffer.isBuffer(rawBody)) {
+      rawBody = rawBody.toString("utf8");
+    } else if (typeof rawBody !== "string") {
+      rawBody = void 0;
+    }
+    if (options.webhookSecret && !options.allowUnsigned && !rawBody) {
+      throw new Error(
+        "Webhook signature verification failed on configuration: webhookSecret is active, but raw request body capture (e.g. request.rawBody) is missing. Please configure a raw-body capture plugin (such as fastify-raw-body) to preserve exact wire bytes."
+      );
+    }
+    const normalizedReq = {
+      body: request.body,
+      rawBody,
+      headers: request.headers
+    };
+    const res = await handleWebhookCore(normalizedReq, options);
+    return reply.code(res.status).send(res.body);
+  };
+}
+
+// adapters/fastify.ts
+function fastifyAdapter(options) {
+  return createFastifyAdapter(options);
+}
+
+// adapters/express.ts
+function createExpressAdapter(options) {
+  validateWebhookCoreOptions(options);
+  return async (req, res) => {
+    try {
+      let rawBody = req.rawBody;
+      if (Buffer.isBuffer(rawBody)) {
+        rawBody = rawBody.toString("utf8");
+      } else if (typeof rawBody !== "string") {
+        rawBody = void 0;
+      }
+      const normalizedReq = {
+        body: req.body,
+        rawBody,
+        headers: req.headers
+      };
+      const result = await handleWebhookCore(normalizedReq, options);
+      res.status(result.status).json(result.body);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  };
+}
+function expressAdapter(options) {
+  return createExpressAdapter(options);
+}
+
+// adapters/http.ts
+function readRawBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+    });
+    req.on("end", () => {
+      resolve(data);
+    });
+    req.on("error", (err) => {
+      reject(err);
+    });
+  });
+}
+function createRawHttpAdapter(options) {
+  validateWebhookCoreOptions(options);
+  return async (req, res) => {
+    try {
+      const rawBody = await readRawBody(req);
+      let body = null;
+      if (rawBody) {
+        try {
+          body = JSON.parse(rawBody);
+        } catch {
+          body = rawBody;
+        }
+      }
+      const normalizedReq = {
+        body,
+        rawBody,
+        headers: req.headers
+      };
+      const result = await handleWebhookCore(normalizedReq, options);
+      res.writeHead(result.status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result.body));
+    } catch (err) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  };
+}
+function rawHttpAdapter(options) {
+  return createRawHttpAdapter(options);
+}
+var httpAdapter = rawHttpAdapter;
+
+// queue/worker.ts
+import { Worker, Queue } from "bullmq";
+
+// queue/lease.ts
+import { randomUUID } from "crypto";
+var ConcurrencyLockError = class extends Error {
+  constructor(waUserId, message) {
+    super(message || `Failed to acquire concurrency lease for user "${waUserId}" within timeout.`);
+    this.waUserId = waUserId;
+    this.name = "ConcurrencyLockError";
+  }
+};
+var InMemoryConcurrencyLeaseService = class {
+  constructor() {
+    this.locks = /* @__PURE__ */ new Map();
+  }
+  async acquire(waUserId, options) {
+    const ttlMs = options?.ttlMs ?? 1e4;
+    const acquireTimeoutMs = options?.acquireTimeoutMs ?? 5e3;
+    const retryIntervalMs = options?.retryIntervalMs ?? 50;
+    const prefix = options?.keyPrefix ?? "fsm:lock:";
+    const leaseKey = `${prefix}${waUserId}`;
+    const token = randomUUID();
+    const startTime = Date.now();
+    while (true) {
+      const now = Date.now();
+      const current = this.locks.get(leaseKey);
+      if (!current || current.expiresAt <= now) {
+        this.locks.set(leaseKey, {
+          token,
+          expiresAt: now + ttlMs
+        });
+        const acquiredAt = now;
+        return {
+          leaseKey,
+          token,
+          waUserId,
+          acquiredAt,
+          ttlMs,
+          release: async () => {
+            const entry = this.locks.get(leaseKey);
+            if (entry && entry.token === token) {
+              this.locks.delete(leaseKey);
+              return true;
+            }
+            return false;
+          }
+        };
+      }
+      if (Date.now() - startTime >= acquireTimeoutMs) {
+        throw new ConcurrencyLockError(
+          waUserId,
+          `Failed to acquire in-memory concurrency lease for user "${waUserId}" within ${acquireTimeoutMs}ms.`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryIntervalMs));
+    }
+  }
+  async isLocked(waUserId, keyPrefix = "fsm:lock:") {
+    const leaseKey = `${keyPrefix}${waUserId}`;
+    const current = this.locks.get(leaseKey);
+    if (!current) return false;
+    return current.expiresAt > Date.now();
+  }
+  clear() {
+    this.locks.clear();
+  }
+};
+var RedisConcurrencyLeaseService = class _RedisConcurrencyLeaseService {
+  constructor(redisClient) {
+    this.redisClient = redisClient;
+  }
+  static {
+    this.UNLOCK_SCRIPT = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("del", KEYS[1])
+    else
+      return 0
+    end
+  `;
+  }
+  async acquire(waUserId, options) {
+    const ttlMs = options?.ttlMs ?? 1e4;
+    const acquireTimeoutMs = options?.acquireTimeoutMs ?? 5e3;
+    const retryIntervalMs = options?.retryIntervalMs ?? 50;
+    const prefix = options?.keyPrefix ?? "fsm:lock:";
+    const leaseKey = `${prefix}${waUserId}`;
+    const token = randomUUID();
+    const startTime = Date.now();
+    while (true) {
+      try {
+        const result = await this.redisClient.set(leaseKey, token, "PX", ttlMs, "NX");
+        if (result === "OK" || result === 1) {
+          const acquiredAt = Date.now();
+          return {
+            leaseKey,
+            token,
+            waUserId,
+            acquiredAt,
+            ttlMs,
+            release: async () => {
+              try {
+                const res = await this.redisClient.eval(
+                  _RedisConcurrencyLeaseService.UNLOCK_SCRIPT,
+                  1,
+                  leaseKey,
+                  token
+                );
+                return res === 1;
+              } catch (err) {
+                console.error(`[RedisConcurrencyLease] Failed to release lease for user ${waUserId}:`, err);
+                return false;
+              }
+            }
+          };
+        }
+      } catch (err) {
+        console.error(`[RedisConcurrencyLease] Redis error while acquiring lock for ${waUserId}:`, err);
+      }
+      if (Date.now() - startTime >= acquireTimeoutMs) {
+        throw new ConcurrencyLockError(
+          waUserId,
+          `Failed to acquire Redis concurrency lease for user "${waUserId}" within ${acquireTimeoutMs}ms.`
+        );
+      }
+      const jitter = Math.floor(Math.random() * 20);
+      await new Promise((resolve) => setTimeout(resolve, retryIntervalMs + jitter));
+    }
+  }
+  async isLocked(waUserId, keyPrefix = "fsm:lock:") {
+    const leaseKey = `${keyPrefix}${waUserId}`;
+    const val = await this.redisClient.get(leaseKey);
+    return val !== null;
+  }
+};
+function createConcurrencyLeaseService(connection) {
+  if (connection && typeof connection.set === "function") {
+    return new RedisConcurrencyLeaseService(connection);
+  }
+  return new InMemoryConcurrencyLeaseService();
+}
+
+// queue/worker.ts
+async function processFSMJob(jobData, options) {
+  const { waUserId, messageText } = jobData;
+  if (!options.flow.nodes || options.flow.nodes.length === 0) {
+    throw new Error(`[FSM Worker] Flow definition "${options.flow.flowId}" is invalid: no nodes defined.`);
+  }
+  let lease = null;
+  if (options.leaseService) {
+    lease = await options.leaseService.acquire(waUserId, options.leaseOptions);
+  }
+  try {
+    const { nextState, result } = await runConversationStep(waUserId, messageText, {
+      persistence: options.persistence,
+      flow: options.flow
+    });
+    let finalNextState = nextState;
+    let sentReply = false;
+    if (result.outboundText) {
+      try {
+        const sendRes = await options.flaresendClient.sendMessage(waUserId, result.outboundText);
+        sentReply = true;
+        if (sendRes?.messageId) {
+          try {
+            const currentState = await options.persistence.load(waUserId);
+            if (currentState) {
+              currentState.context.lastOutboundMessageId = sendRes.messageId;
+              await options.persistence.save(currentState);
+              finalNextState = currentState;
+            }
+          } catch (telemetryErr) {
+            console.warn(`Failed to persist lastOutboundMessageId for ${waUserId}`, telemetryErr);
+          }
+        }
+      } catch (err) {
+        const isAmbiguous = err?.isAmbiguous ?? true;
+        if (isAmbiguous) {
+          console.warn(
+            `[AMBIGUOUS_SEND_FAILURE] Outbound send failed with unconfirmed delivery status for user ${waUserId}. State saved successfully. Delegating to resend queue with conservative initial backoff.`,
+            err
+          );
+        } else {
+          console.error(
+            `[KNOWN_NOT_SENT_FAILURE] Outbound send failed before transmission for user ${waUserId}. State saved successfully. Delegating to resend queue with standard initial backoff.`,
+            err
+          );
+        }
+        if (options.resendQueue) {
+          const initialDelay = isAmbiguous ? 5e3 : 1e3;
+          await options.resendQueue.add(
+            "resend-message",
+            { waUserId, outboundText: result.outboundText, isAmbiguous },
+            {
+              attempts: 3,
+              backoff: {
+                type: "exponential",
+                delay: initialDelay
+              }
+            }
+          );
+        } else {
+          throw err;
+        }
+      }
+    }
+    return {
+      nextState: finalNextState,
+      sentReply,
+      result
+    };
+  } finally {
+    if (lease) {
+      try {
+        await lease.release();
+      } catch (releaseErr) {
+        console.warn(`[FSM Worker] Failed to release concurrency lease for user ${waUserId}:`, releaseErr);
+      }
+    }
+  }
+}
+function createFSMWorker(options) {
+  const queueName = options.queueName || "webhook-messages";
+  const resendQueueName = options.resendQueueName || `${queueName}-resends`;
+  const resendQueue = new Queue(resendQueueName, {
+    connection: options.connection
+  });
+  const resendWorker = new Worker(
+    resendQueueName,
+    async (job) => {
+      const { waUserId, outboundText, isAmbiguous } = job.data;
+      if (isAmbiguous) {
+        console.warn(`[Resend Worker AMBIGUOUS_RETRY] Attempting delivery retry for unconfirmed send (user: ${waUserId}, job: ${job.id})`);
+      } else {
+        console.log(`[Resend Worker STANDARD_RETRY] Attempting delivery retry for known-not-sent message (user: ${waUserId}, job: ${job.id})`);
+      }
+      const res = await options.flaresendClient.sendMessage(waUserId, outboundText);
+      if (res?.messageId) {
+        try {
+          const currentState = await options.persistence.load(waUserId);
+          if (currentState) {
+            currentState.context.lastOutboundMessageId = res.messageId;
+            await options.persistence.save(currentState);
+          }
+        } catch (stateErr) {
+          console.warn(`[Resend Worker] Failed to update lastOutboundMessageId in state for user ${waUserId}`, stateErr);
+        }
+      }
+    },
+    {
+      connection: options.connection,
+      concurrency: options.concurrency || 1
+    }
+  );
+  resendWorker.on("completed", (job) => {
+    console.log(`[Resend Worker] Resend job ${job.id} completed successfully.`);
+  });
+  resendWorker.on("failed", (job, err) => {
+    console.error(`[Resend Worker] Resend job ${job?.id} failed after maximum retry attempts. Error:`, err);
+  });
+  const leaseService = options.leaseService ?? (options.enableConcurrencyLease !== false && options.connection ? createConcurrencyLeaseService(options.connection) : void 0);
+  const worker = new Worker(
+    queueName,
+    async (job) => {
+      console.log(`[FSM Worker] Received queued job ${job.id} for user: ${job.data.waUserId}`);
+      const { wamid, waUserId, messageText, timestamp } = job.data;
+      if (!waUserId || typeof messageText !== "string") {
+        throw new Error(`[FSM Worker] Invalid job payload: ${JSON.stringify(job.data)}`);
+      }
+      return await processFSMJob(
+        { wamid, waUserId, messageText, timestamp },
+        {
+          persistence: options.persistence,
+          flow: options.flow,
+          flaresendClient: options.flaresendClient,
+          resendQueue,
+          leaseService,
+          leaseOptions: options.leaseOptions
+        }
+      );
+    },
+    {
+      connection: options.connection,
+      concurrency: options.concurrency || 1
+    }
+  );
+  worker.on("completed", (job) => {
+    console.log(`[FSM Worker] Job ${job.id} completed successfully.`);
+  });
+  worker.on("failed", (job, err) => {
+    console.error(`[FSM Worker] Job ${job?.id} failed with error:`, err);
+  });
+  const originalClose = worker.close.bind(worker);
+  worker.close = async () => {
+    console.log(`[FSM Worker] Initiating graceful shutdown of FSM worker and companion resend system...`);
+    await Promise.all([
+      originalClose(),
+      resendWorker.close(),
+      resendQueue.close()
+    ]);
+  };
+  return worker;
+}
+
+// analytics/trace.ts
+var TraceCollector = class {
+  constructor(initialTraces) {
+    this.traces = [];
+    this.listeners = [];
+    if (initialTraces) {
+      this.traces = [...initialTraces];
+    }
+  }
+  logTurn(turn) {
+    const fullTurn = {
+      ...turn,
+      id: `turn_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`,
+      timestamp: Date.now()
+    };
+    this.traces.push(fullTurn);
+    this.listeners.forEach((listener) => listener(fullTurn));
+    return fullTurn;
+  }
+  onTurn(listener) {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  }
+  getTraces() {
+    return [...this.traces];
+  }
+  getSessions() {
+    const sessionMap = /* @__PURE__ */ new Map();
+    for (const turn of this.traces) {
+      if (!sessionMap.has(turn.sessionId)) {
+        sessionMap.set(turn.sessionId, []);
+      }
+      sessionMap.get(turn.sessionId).push(turn);
+    }
+    const sessions = [];
+    sessionMap.forEach((turns, sessionId) => {
+      turns.sort((a, b) => a.timestamp - b.timestamp);
+      const lastTurn = turns[turns.length - 1];
+      const totalRetries = turns.reduce((acc, t) => acc + (t.retryCount > 0 ? 1 : 0), 0);
+      sessions.push({
+        sessionId,
+        flowId: turns[0].flowId,
+        startTime: turns[0].timestamp,
+        endTime: lastTurn.timestamp,
+        turns,
+        finalStatus: lastTurn.status,
+        totalRetries
+      });
+    });
+    return sessions.sort((a, b) => b.endTime - a.endTime);
+  }
+  computeMetrics(flow) {
+    const sessions = this.getSessions();
+    const totalSessions = sessions.length;
+    if (totalSessions === 0) {
+      return {
+        totalSessions: 0,
+        completedSessions: 0,
+        escalatedSessions: 0,
+        activeSessions: 0,
+        containmentRate: 100,
+        completionRate: 0,
+        escalationRate: 0,
+        avgTurnsPerSession: 0,
+        totalRetries: 0,
+        nodeStats: {}
+      };
+    }
+    let completedSessions = 0;
+    let escalatedSessions = 0;
+    let activeSessions = 0;
+    let totalTurnsCount = 0;
+    let totalRetries = 0;
+    const nodeStats = {};
+    if (flow) {
+      for (const node of flow.nodes) {
+        nodeStats[node.id] = {
+          visits: 0,
+          retries: 0,
+          dropOffs: 0,
+          unhandledInputs: [],
+          patternBreakdown: {}
+        };
+      }
+    }
+    for (const session of sessions) {
+      totalTurnsCount += session.turns.length;
+      if (session.finalStatus === "completed") completedSessions++;
+      else if (session.finalStatus === "escalated") escalatedSessions++;
+      else activeSessions++;
+      for (let i = 0; i < session.turns.length; i++) {
+        const turn = session.turns[i];
+        const isLastTurn = i === session.turns.length - 1;
+        if (!nodeStats[turn.fromNodeId]) {
+          nodeStats[turn.fromNodeId] = {
+            visits: 0,
+            retries: 0,
+            dropOffs: 0,
+            unhandledInputs: [],
+            patternBreakdown: {}
+          };
+        }
+        const stat = nodeStats[turn.fromNodeId];
+        stat.visits++;
+        if (turn.retryCount > 0) {
+          stat.retries++;
+          if (!stat.unhandledInputs.includes(turn.rawInput)) {
+            stat.unhandledInputs.push(turn.rawInput);
+          }
+        }
+        const patternKey = turn.matchedPattern || "[unmatched]";
+        stat.patternBreakdown[patternKey] = (stat.patternBreakdown[patternKey] || 0) + 1;
+        if (isLastTurn && session.finalStatus !== "completed") {
+          stat.dropOffs++;
+        }
+      }
+    }
+    const containmentRate = totalSessions > 0 ? Math.round((totalSessions - escalatedSessions) / totalSessions * 100) : 100;
+    const completionRate = Math.round(completedSessions / totalSessions * 100);
+    const escalationRate = Math.round(escalatedSessions / totalSessions * 100);
+    const avgTurnsPerSession = Number((totalTurnsCount / totalSessions).toFixed(1));
+    return {
+      totalSessions,
+      completedSessions,
+      escalatedSessions,
+      activeSessions,
+      containmentRate,
+      completionRate,
+      escalationRate,
+      avgTurnsPerSession,
+      totalRetries,
+      nodeStats
+    };
+  }
+  clear() {
+    this.traces = [];
+  }
+};
+
+// evals/evaluator.ts
+var Evaluator = class {
+  constructor(flow) {
+    this.flow = flow;
+  }
+  async runScenario(scenario) {
+    const startTime = Date.now();
+    const engine = new FSMEngine(this.flow);
+    let state = engine.createInitialState(`eval_user_${scenario.id}`);
+    if (scenario.initialContext) {
+      state = {
+        ...state,
+        context: { ...scenario.initialContext }
+      };
+    }
+    const stepResults = [];
+    const visitedNodes = /* @__PURE__ */ new Set([state.currentNodeId]);
+    let overallPassed = true;
+    for (let i = 0; i < scenario.steps.length; i++) {
+      const step = scenario.steps[i];
+      const result = await engine.transition(state, step.input);
+      state = result.nextState;
+      visitedNodes.add(state.currentNodeId);
+      let stepPassed = true;
+      const failureReasons = [];
+      if (step.expectedNodeId && state.currentNodeId !== step.expectedNodeId) {
+        stepPassed = false;
+        failureReasons.push(
+          `Expected node "${step.expectedNodeId}", but transitioned to "${state.currentNodeId}"`
+        );
+      }
+      if (step.expectedOutboundPattern) {
+        const outbound = result.outboundText ?? "";
+        if (typeof step.expectedOutboundPattern === "string") {
+          if (!outbound.toLowerCase().includes(step.expectedOutboundPattern.toLowerCase())) {
+            stepPassed = false;
+            failureReasons.push(
+              `Outbound text "${outbound}" did not contain expected substring "${step.expectedOutboundPattern}"`
+            );
+          }
+        } else if (step.expectedOutboundPattern instanceof RegExp) {
+          if (!step.expectedOutboundPattern.test(outbound)) {
+            stepPassed = false;
+            failureReasons.push(
+              `Outbound text "${outbound}" did not match regex pattern ${step.expectedOutboundPattern}`
+            );
+          }
+        }
+      }
+      if (step.expectedContext) {
+        for (const [key, val] of Object.entries(step.expectedContext)) {
+          if (state.context[key] !== val) {
+            stepPassed = false;
+            failureReasons.push(
+              `Context key "${key}" expected value ${JSON.stringify(val)}, got ${JSON.stringify(state.context[key])}`
+            );
+          }
+        }
+      }
+      if (step.expectEscalated && state.status !== "escalated") {
+        stepPassed = false;
+        failureReasons.push(`Expected conversation to be escalated, but status was "${state.status}"`);
+      }
+      if (step.expectCompleted && state.status !== "completed") {
+        stepPassed = false;
+        failureReasons.push(`Expected conversation to be completed, but status was "${state.status}"`);
+      }
+      if (!stepPassed) {
+        overallPassed = false;
+      }
+      stepResults.push({
+        stepIndex: i + 1,
+        input: step.input,
+        actualNodeId: state.currentNodeId,
+        expectedNodeId: step.expectedNodeId,
+        actualOutbound: result.outboundText,
+        expectedOutboundPattern: step.expectedOutboundPattern,
+        actualStatus: state.status,
+        actualContext: { ...state.context },
+        passed: stepPassed,
+        failureReason: failureReasons.join("; ")
+      });
+    }
+    return {
+      scenarioId: scenario.id,
+      scenarioName: scenario.name,
+      passed: overallPassed,
+      stepResults,
+      durationMs: Date.now() - startTime,
+      visitedNodeIds: Array.from(visitedNodes)
+    };
+  }
+  async runSuite(scenarios) {
+    const startTime = Date.now();
+    const scenarioResults = [];
+    const allVisitedNodes = /* @__PURE__ */ new Set();
+    for (const scenario of scenarios) {
+      const res = await this.runScenario(scenario);
+      scenarioResults.push(res);
+      res.visitedNodeIds.forEach((id) => allVisitedNodes.add(id));
+    }
+    const totalScenarios = scenarios.length;
+    const passedScenarios = scenarioResults.filter((r) => r.passed).length;
+    const failedScenarios = totalScenarios - passedScenarios;
+    const passRate = totalScenarios > 0 ? Math.round(passedScenarios / totalScenarios * 100) : 0;
+    const allNodeIds = this.flow.nodes.map((n) => n.id);
+    const coveredNodeIds = allNodeIds.filter((id) => allVisitedNodes.has(id));
+    const uncoveredNodeIds = allNodeIds.filter((id) => !allVisitedNodes.has(id));
+    const nodeCoveragePercentage = allNodeIds.length > 0 ? Math.round(coveredNodeIds.length / allNodeIds.length * 100) : 100;
+    return {
+      totalScenarios,
+      passedScenarios,
+      failedScenarios,
+      passRate,
+      nodeCoveragePercentage,
+      coveredNodeIds,
+      uncoveredNodeIds,
+      scenarioResults,
+      totalDurationMs: Date.now() - startTime
+    };
+  }
+};
+export {
+  ActionNodeBuilder,
+  AmbiguousSendError,
+  Bot,
+  CallbackPersistenceAdapter,
+  CompileError,
+  ConcurrencyLockError,
+  Context,
+  Evaluator,
+  FSMEngine,
+  FlaresendClient,
+  FlaresendSendError,
+  FlowNodeBuilder,
+  GlobalTransitionBuilder,
+  HandoffNodeBuilder,
+  IdempotencyService,
+  InMemoryConcurrencyLeaseService,
+  KnownNotSentError,
+  MongoosePersistenceAdapter,
+  OptimisticConcurrencyError,
+  RedisConcurrencyLeaseService,
+  TraceCollector,
+  classifyFlaresendError,
+  createConcurrencyLeaseService,
+  createExpressAdapter,
+  createFSMWorker,
+  createFastifyAdapter,
+  createLiteralMatcher,
+  createRawHttpAdapter,
+  expressAdapter,
+  extractWebhookPayload,
+  fastifyAdapter,
+  handleWebhookCore,
+  httpAdapter,
+  matchesAny,
+  processFSMJob,
+  rawHttpAdapter,
+  registerFlowDefinition,
+  runConversationStep,
+  verifyWebhookSignature
+};