@henry-dev/botkit 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,749 @@
+import mongoose from 'mongoose';
+import Redis from 'ioredis';
+import { Worker, Queue } from 'bullmq';
+
+interface MatchResult {
+    readonly matched: boolean;
+    readonly pattern: string;
+    readonly confidence: number;
+}
+interface MatcherOptions {
+    readonly boundary?: boolean;
+    readonly normalize?: boolean;
+    readonly excludeIf?: ReadonlyArray<string>;
+}
+interface CompiledMatcher {
+    readonly patterns: ReadonlyArray<string>;
+    readonly normalize: (text: string) => string;
+    readonly match: (text: string) => MatchResult;
+}
+
+declare class Context {
+    private data;
+    constructor(initialData?: Record<string, any>);
+    set(key: string, value: any): void;
+    get(key: string): any;
+    has(key: string): boolean;
+    delete(key: string): void;
+    clear(): void;
+    all(): Record<string, any>;
+}
+
+interface Transition {
+    readonly targetNodeId: string;
+    readonly patterns?: ReadonlyArray<string>;
+}
+interface LifecycleEventInfo {
+    readonly fromNodeId?: string;
+    readonly toNodeId?: string;
+    readonly triggerText?: string;
+    readonly isInitial?: boolean;
+}
+type LifecycleHook = (ctx: Context, info: LifecycleEventInfo) => void | Promise<void>;
+interface ActionBranch<T = any> {
+    readonly targetNodeId: string;
+    readonly handler?: (data: T, ctx: Context) => void | Promise<void>;
+}
+type ActionFunction<T = any> = (ctx: Context) => Promise<T> | T;
+interface ActionDefinition<T = any> {
+    readonly execute: ActionFunction<T>;
+    readonly timeoutMs?: number;
+    readonly onSuccess?: ActionBranch<T>;
+    readonly onFailure?: ActionBranch<any>;
+    readonly onTimeout?: ActionBranch<Error>;
+}
+interface GlobalTransition {
+    readonly id: string;
+    readonly matcher: CompiledMatcher;
+    readonly patterns?: ReadonlyArray<string>;
+    readonly targetNodeId: string;
+    readonly responseFn?: (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>;
+    readonly priority: "high" | "low";
+}
+interface HandoffSession {
+    readonly state: "pending" | "connected" | "resolved" | "timed_out";
+    readonly reason?: string;
+    readonly assignedAgentId?: string;
+    readonly requestedAt: number;
+    readonly connectedAt?: number;
+    readonly resolvedAt?: number;
+    readonly resumeNodeId?: string;
+    readonly timeoutMs?: number;
+    readonly fallbackNodeId?: string;
+    readonly queueMessage?: string | null;
+    readonly metadata?: Record<string, any>;
+}
+interface HandoffDefinition {
+    readonly reason?: string;
+    readonly timeoutMs?: number;
+    readonly resumeNodeId?: string;
+    readonly fallbackNodeId?: string;
+    readonly queueMessage?: string | null;
+    readonly metadata?: Record<string, any>;
+}
+interface FlowNode {
+    readonly id: string;
+    readonly text: string;
+    readonly matcher: CompiledMatcher;
+    readonly transitions: ReadonlyArray<Transition>;
+    readonly fallbackText: string | ((ctx: Context) => string | Promise<string>);
+    readonly maxRetries: number;
+    readonly onMaxRetriesFn?: (ctx: Context) => void | Promise<void>;
+    readonly responseFn?: (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>;
+    readonly onEnter?: LifecycleHook;
+    readonly onExit?: LifecycleHook;
+    readonly ignoreGlobals?: boolean | ReadonlyArray<string>;
+    readonly isAction?: boolean;
+    readonly action?: ActionDefinition;
+    readonly isHandoff?: boolean;
+    readonly handoff?: HandoffDefinition;
+}
+interface FlowDefinition {
+    readonly flowId: string;
+    readonly version: number;
+    readonly nodes: ReadonlyArray<FlowNode>;
+    readonly globals?: ReadonlyArray<GlobalTransition>;
+}
+interface ConversationState {
+    readonly waUserId: string;
+    readonly flowId: string;
+    readonly flowVersion: number;
+    readonly currentNodeId: string;
+    readonly context: Record<string, any>;
+    readonly retryCount: number;
+    readonly status: "active" | "escalated" | "completed" | "abandoned" | "handoff";
+    readonly version?: number;
+    readonly handoff?: HandoffSession;
+}
+interface TransitionResult {
+    readonly nextState: ConversationState;
+    readonly outboundText: string | null;
+    readonly matchedGlobalId?: string;
+    readonly suspended?: boolean;
+}
+interface LegalCommandInfo {
+    readonly kind: "global" | "local" | "handoff" | "action";
+    readonly command: string;
+    readonly targetNodeId?: string;
+    readonly description?: string;
+}
+interface AvailableCommandsResult {
+    readonly currentNodeId: string;
+    readonly status: "active" | "escalated" | "completed" | "abandoned" | "handoff";
+    readonly handoffState?: "pending" | "connected" | "resolved" | "timed_out";
+    readonly commands: ReadonlyArray<LegalCommandInfo>;
+}
+
+declare class CompileError extends Error {
+    constructor(message: string);
+}
+interface ActionDefinitionOptions<T = any> {
+    execute?: ActionFunction<T>;
+    timeoutMs?: number;
+    onSuccess?: string | ActionBranch<T>;
+    onFailure?: string | ActionBranch<any>;
+    onTimeout?: string | ActionBranch<Error>;
+}
+declare class ActionNodeBuilder {
+    private bot;
+    id: string;
+    private _actionFn?;
+    private _timeoutMs;
+    private _onSuccess?;
+    private _onFailure?;
+    private _onTimeout?;
+    private _onEnter?;
+    private _onExit?;
+    private _text;
+    constructor(bot: Bot, id: string, options?: ActionDefinitionOptions);
+    execute<T = any>(fn: ActionFunction<T>): this;
+    timeout(ms: number): this;
+    text(msg: string): this;
+    onSuccess<T = any>(targetNodeId: string, handler?: (data: T, ctx: Context) => void | Promise<void>): this;
+    onFailure(targetNodeId: string, handler?: (err: any, ctx: Context) => void | Promise<void>): this;
+    onTimeout(targetNodeId: string, handler?: (err: Error, ctx: Context) => void | Promise<void>): this;
+    onEnter(fn: LifecycleHook): this;
+    onExit(fn: LifecycleHook): this;
+    ask(text: string): FlowNodeBuilder;
+    action(id: string, options?: ActionDefinitionOptions): ActionNodeBuilder;
+    handoff(id: string, options?: HandoffNodeOptions): HandoffNodeBuilder;
+    global(matcher: CompiledMatcher | string[] | string, options?: GlobalTransitionOptions | string): GlobalTransitionBuilder;
+    getId(): string;
+    getText(): string;
+    getActionFn(): ActionFunction;
+    getTimeoutMs(): number;
+    getOnSuccess(): ActionBranch<any>;
+    getOnFailure(): ActionBranch<any>;
+    getOnTimeout(): ActionBranch<any>;
+    getOnEnterFn(): LifecycleHook;
+    getOnExitFn(): LifecycleHook;
+}
+interface HandoffNodeOptions {
+    reason?: string;
+    timeoutMs?: number;
+    resumeNodeId?: string;
+    fallbackNodeId?: string;
+    message?: string;
+    queueMessage?: string | null;
+    metadata?: Record<string, any>;
+}
+declare class HandoffNodeBuilder {
+    private bot;
+    id: string;
+    private _reason?;
+    private _timeoutMs;
+    private _resumeNodeId?;
+    private _fallbackNodeId?;
+    private _text;
+    private _queueMessage?;
+    private _metadata?;
+    private _onEnter?;
+    private _onExit?;
+    private _ignoreGlobals?;
+    constructor(bot: Bot, id: string, options?: HandoffNodeOptions);
+    reason(text: string): this;
+    timeout(ms: number): this;
+    resumeAt(targetNodeId: string): this;
+    fallbackTo(targetNodeId: string): this;
+    message(text: string): this;
+    queueMessage(text: string | null): this;
+    metadata(data: Record<string, any>): this;
+    onEnter(fn: LifecycleHook): this;
+    onExit(fn: LifecycleHook): this;
+    ignoreGlobals(ignore?: boolean | string[]): this;
+    ask(text: string): FlowNodeBuilder;
+    action(id: string, options?: ActionDefinitionOptions): ActionNodeBuilder;
+    handoff(id: string, options?: HandoffNodeOptions): HandoffNodeBuilder;
+    global(matcher: CompiledMatcher | string[] | string, options?: GlobalTransitionOptions | string): GlobalTransitionBuilder;
+    getId(): string;
+    getText(): string;
+    getReason(): string;
+    getTimeoutMs(): number;
+    getResumeNodeId(): string;
+    getFallbackNodeId(): string;
+    getQueueMessage(): string;
+    getMetadata(): Record<string, any>;
+    getOnEnterFn(): LifecycleHook;
+    getOnExitFn(): LifecycleHook;
+    getIgnoreGlobals(): boolean | string[];
+}
+interface GlobalTransitionOptions {
+    id?: string;
+    target?: string;
+    targetNodeId?: string;
+    priority?: "high" | "low";
+    response?: (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>;
+    matcherOptions?: MatcherOptions;
+}
+declare class GlobalTransitionBuilder {
+    private bot;
+    private _id?;
+    private _targetNodeId?;
+    private _patterns;
+    private _opts?;
+    private _matcher?;
+    private _priority;
+    private _responseFn?;
+    constructor(bot: Bot, matcher: CompiledMatcher | string[] | string, options?: GlobalTransitionOptions | string);
+    id(customId: string): this;
+    then(targetNodeId: string): this;
+    response(fn: (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>): this;
+    priority(p: "high" | "low"): this;
+    getId(defaultId: string): string;
+    getTargetNodeId(): string | undefined;
+    getPatterns(): string[];
+    getOpts(): MatcherOptions | undefined;
+    getMatcher(): CompiledMatcher | undefined;
+    getPriority(): "high" | "low";
+    getResponseFn(): (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>;
+    ask(text: string): FlowNodeBuilder;
+    action(id: string, options?: ActionDefinitionOptions): ActionNodeBuilder;
+    handoff(id: string, options?: HandoffNodeOptions): HandoffNodeBuilder;
+    global(matcher: CompiledMatcher | string[] | string, options?: GlobalTransitionOptions | string): GlobalTransitionBuilder;
+}
+interface PendingBranch {
+    patterns: string[];
+    opts?: MatcherOptions;
+    matcher?: CompiledMatcher;
+    targetNodeId?: string;
+}
+declare class FlowNodeBuilder {
+    private bot;
+    defaultId: string;
+    text: string;
+    private _customId?;
+    private _branches;
+    private _responseFn?;
+    private _fallbackText;
+    private _maxRetries;
+    private _onMaxRetriesFn?;
+    private _onEnter?;
+    private _onExit?;
+    private _ignoreGlobals?;
+    constructor(bot: Bot, defaultId: string, text: string);
+    getId(): string;
+    id(customId: string): this;
+    expect(matcher: CompiledMatcher | string[] | string, opts?: MatcherOptions): this;
+    then(targetNodeId: string): this;
+    response(fn: (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>): this;
+    fallback(textOrFn: string | ((ctx: Context) => string | Promise<string>)): this;
+    retries(n: number): this;
+    onMaxRetries(fn: (ctx: Context) => void | Promise<void>): this;
+    onEnter(fn: LifecycleHook): this;
+    onExit(fn: LifecycleHook): this;
+    ignoreGlobals(ignore?: boolean | string[]): this;
+    ask(text: string): FlowNodeBuilder;
+    action(id: string, options?: ActionDefinitionOptions): ActionNodeBuilder;
+    handoff(id: string, options?: HandoffNodeOptions): HandoffNodeBuilder;
+    global(matcher: CompiledMatcher | string[] | string, options?: GlobalTransitionOptions | string): GlobalTransitionBuilder;
+    getBranches(): ReadonlyArray<PendingBranch>;
+    getResponseFn(): (answer: {
+        raw: string;
+        pattern: string;
+    }, ctx: Context) => void | Promise<void>;
+    getFallbackText(): string | ((ctx: Context) => string | Promise<string>);
+    getMaxRetries(): number;
+    getOnMaxRetriesFn(): (ctx: Context) => void | Promise<void>;
+    getOnEnterFn(): LifecycleHook;
+    getOnExitFn(): LifecycleHook;
+    getIgnoreGlobals(): boolean | string[];
+}
+declare class Bot {
+    flowId: string;
+    version: number;
+    private builders;
+    private actionBuilders;
+    private handoffBuilders;
+    private globalBuilders;
+    constructor(flowId: string, version?: number);
+    ask(text: string): FlowNodeBuilder;
+    action(id: string, options?: ActionDefinitionOptions): ActionNodeBuilder;
+    handoff(id: string, options?: HandoffNodeOptions): HandoffNodeBuilder;
+    global(matcher: CompiledMatcher | string[] | string, options?: GlobalTransitionOptions | string): GlobalTransitionBuilder;
+    escalate(ctx: Context): void;
+    compile(): FlowDefinition;
+}
+
+declare class OptimisticConcurrencyError extends Error {
+    waUserId: string;
+    expectedVersion: number;
+    constructor(waUserId: string, expectedVersion: number);
+}
+interface PersistenceAdapter {
+    load(waUserId: string): Promise<ConversationState | null>;
+    save(state: ConversationState): Promise<void>;
+    loadFlowDefinition(flowId: string, version: number): Promise<FlowDefinition | null>;
+    saveFlowDefinition(flow: FlowDefinition): Promise<void>;
+}
+declare function registerFlowDefinition(flow: FlowDefinition): void;
+declare class MongoosePersistenceAdapter implements PersistenceAdapter {
+    private ConversationStateModel;
+    private FlowDefinitionModel;
+    constructor(connection?: mongoose.Connection);
+    load(waUserId: string): Promise<ConversationState | null>;
+    save(state: ConversationState): Promise<void>;
+    loadFlowDefinition(flowId: string, version: number): Promise<FlowDefinition | null>;
+    saveFlowDefinition(flow: FlowDefinition): Promise<void>;
+}
+interface CallbackPersistenceAdapterOptions {
+    load: (waUserId: string) => Promise<ConversationState | null>;
+    save: (state: ConversationState) => Promise<void>;
+    loadFlowDefinition: (flowId: string, version: number) => Promise<FlowDefinition | null>;
+    saveFlowDefinition: (flow: FlowDefinition) => Promise<void>;
+}
+declare class CallbackPersistenceAdapter implements PersistenceAdapter {
+    private options;
+    constructor(options: CallbackPersistenceAdapterOptions);
+    load(waUserId: string): Promise<ConversationState>;
+    save(state: ConversationState): Promise<void>;
+    loadFlowDefinition(flowId: string, version: number): Promise<FlowDefinition>;
+    saveFlowDefinition(flow: FlowDefinition): Promise<void>;
+}
+
+declare class FSMEngine {
+    private flow;
+    constructor(flow: FlowDefinition);
+    createInitialState(waUserId: string): ConversationState;
+    executeInitialEnter(state: ConversationState): Promise<ConversationState>;
+    executeActionNode(state: ConversationState): Promise<TransitionResult>;
+    private isGlobalIgnored;
+    private safelyExecuteHook;
+    private resolveDestination;
+    private executeGlobalTransition;
+    transition(state: ConversationState, inboundText: string): Promise<TransitionResult>;
+    private handleFallback;
+    connectAgent(state: ConversationState, agentId: string, metadata?: Record<string, any>): ConversationState;
+    resolveHandoff(state: ConversationState, options?: {
+        resumeNodeId?: string;
+        resolutionNotes?: string;
+        contextUpdates?: Record<string, any>;
+    }): Promise<TransitionResult>;
+    checkHandoffTimeout(state: ConversationState, currentTime?: number): Promise<TransitionResult | null>;
+    getAvailableCommands(state: ConversationState): AvailableCommandsResult;
+    getLegalTransitions(state: ConversationState): AvailableCommandsResult;
+}
+declare function runConversationStep(waUserId: string, messageText: string, options: {
+    persistence: PersistenceAdapter;
+    flow: FlowDefinition;
+}): Promise<{
+    nextState: ConversationState;
+    result: TransitionResult;
+}>;
+
+declare function createLiteralMatcher(patterns: string[], opts?: MatcherOptions): CompiledMatcher;
+declare function matchesAny(patterns: string[], opts?: MatcherOptions): CompiledMatcher;
+
+declare class IdempotencyService {
+    private redis;
+    constructor(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.
+     */
+    checkAndLock(wamid: string, ttlSeconds?: number): Promise<boolean>;
+    /**
+     * Releases/deletes the idempotency lock for a message ID.
+     * Useful to roll back locks when downstream operations (e.g. queue enqueue) fail.
+     */
+    release(wamid: string): Promise<void>;
+}
+
+declare class FlaresendSendError extends Error {
+    isAmbiguous: boolean;
+    statusCode?: number;
+    code?: string;
+    constructor(message: string, isAmbiguous: boolean, statusCode?: number, code?: string);
+}
+declare class KnownNotSentError extends FlaresendSendError {
+    constructor(message: string, statusCode?: number, code?: string);
+}
+declare class AmbiguousSendError extends FlaresendSendError {
+    constructor(message: string, statusCode?: number, code?: string);
+}
+/**
+ * Classifies an error caught during Flaresend message transmission into
+ * a KnownNotSentError (rejected before send) or AmbiguousSendError (unconfirmed delivery status).
+ */
+declare function classifyFlaresendError(err: any): FlaresendSendError;
+interface FlaresendClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    mock?: boolean;
+}
+declare class FlaresendClient {
+    private sdk;
+    private isMock;
+    constructor(options?: FlaresendClientOptions);
+    /**
+     * Sends an outbound WhatsApp message to the recipient using the official Flaresend SDK.
+     * Categorizes any transmission errors into KnownNotSentError or AmbiguousSendError.
+     */
+    sendMessage(to: string, text: string): Promise<{
+        success: boolean;
+        messageId?: string;
+    }>;
+}
+
+interface NormalizedRequest {
+    body: any;
+    rawBody?: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface NormalizedResponse {
+    status: number;
+    body: any;
+}
+interface WebhookJob {
+    wamid: string;
+    waUserId: string;
+    messageText: string;
+    timestamp: number;
+}
+interface WebhookQueue {
+    add(name: string, data: WebhookJob): Promise<any>;
+}
+interface WebhookCoreOptions {
+    idempotencyService: IdempotencyService;
+    queue: WebhookQueue;
+    webhookSecret?: string;
+    allowUnsigned?: boolean;
+}
+interface NormalizedMessage {
+    id: string;
+    from: string;
+    text: string;
+    timestamp: number;
+}
+interface NormalizedStatus {
+    id: string;
+    status: string;
+    recipient_id: string;
+    timestamp: number;
+}
+/**
+ * Robust utility to parse both flat Flaresend payloads and nested Meta/WhatsApp Cloud API payloads.
+ */
+declare function extractWebhookPayload(body: any): {
+    messages: NormalizedMessage[];
+    statuses: NormalizedStatus[];
+};
+/**
+ * Validates HMAC-SHA256 signatures of webhook payloads.
+ *
+ * PROVISIONAL IMPLEMENTATION NOTE:
+ * The Flaresend SDK contains a provisional signature validation placeholder helper:
+ *   `const isValid = flaresend.webhooks.validateSignature(JSON.stringify(req.body), signatureHeader, secret);`
+ *
+ * However, since Flaresend has not officially finalized or published the exact payload/HMAC scheme details,
+ * we implement this robust, timing-safe validation. It covers standard Meta-style `X-Hub-Signature-256`
+ * signatures (since Flaresend likely proxies standard WhatsApp Cloud API webhooks) and custom `X-Flaresend-Signature` headers.
+ * Once Flaresend publishes exact specifications for their SDK's `validateSignature`, this wrapper can delegate
+ * directly to it.
+ */
+declare function verifyWebhookSignature(rawBody: string, signatureHeader: string | undefined, secret: string): boolean;
+/**
+ * Framework-agnostic core webhook handler.
+ * Validates request signature, extracts messages/statuses, runs idempotency checks,
+ * and enqueues new messages as BullMQ jobs.
+ */
+declare function handleWebhookCore(req: NormalizedRequest, options: WebhookCoreOptions): Promise<NormalizedResponse>;
+declare function createFastifyAdapter(options: WebhookCoreOptions): (request: any, reply: any) => Promise<any>;
+
+/**
+ * Fastify route handler adapter for the framework-agnostic webhook handler core.
+ * Usage:
+ *   fastify.post("/webhook", fastifyAdapter(options));
+ */
+declare function fastifyAdapter(options: WebhookCoreOptions): (request: any, reply: any) => Promise<any>;
+
+/**
+ * Express middleware / route handler adapter wrapping handleWebhookCore.
+ * Usage:
+ *   app.post("/webhook", expressAdapter(options));
+ */
+declare function createExpressAdapter(options: WebhookCoreOptions): (req: any, res: any) => Promise<void>;
+declare function expressAdapter(options: WebhookCoreOptions): (req: any, res: any) => Promise<void>;
+
+/**
+ * Raw Node.js HTTP server adapter for the framework-agnostic webhook handler core.
+ * Usage:
+ *   import { rawHttpAdapter } from "@henry-dev/botkit/http";
+ *   http.createServer(rawHttpAdapter(options)).listen(3000);
+ */
+declare function createRawHttpAdapter(options: WebhookCoreOptions): (req: any, res: any) => Promise<void>;
+declare function rawHttpAdapter(options: WebhookCoreOptions): (req: any, res: any) => Promise<void>;
+declare const httpAdapter: typeof rawHttpAdapter;
+
+declare class ConcurrencyLockError extends Error {
+    waUserId: string;
+    constructor(waUserId: string, message?: string);
+}
+interface ConcurrencyLease {
+    readonly leaseKey: string;
+    readonly token: string;
+    readonly waUserId: string;
+    readonly acquiredAt: number;
+    readonly ttlMs: number;
+    release(): Promise<boolean>;
+}
+interface ConcurrencyLeaseOptions {
+    ttlMs?: number;
+    acquireTimeoutMs?: number;
+    retryIntervalMs?: number;
+    keyPrefix?: string;
+}
+interface ConcurrencyLeaseService {
+    acquire(waUserId: string, options?: ConcurrencyLeaseOptions): Promise<ConcurrencyLease>;
+    isLocked(waUserId: string): Promise<boolean>;
+}
+/**
+ * In-memory lease service for unit testing, development, and single-instance deployments.
+ */
+declare class InMemoryConcurrencyLeaseService implements ConcurrencyLeaseService {
+    private locks;
+    acquire(waUserId: string, options?: ConcurrencyLeaseOptions): Promise<ConcurrencyLease>;
+    isLocked(waUserId: string, keyPrefix?: string): Promise<boolean>;
+    clear(): void;
+}
+/**
+ * Production Redis distributed lock using SET NX PX and atomic Lua unlock script.
+ */
+declare class RedisConcurrencyLeaseService implements ConcurrencyLeaseService {
+    private redisClient;
+    private static readonly UNLOCK_SCRIPT;
+    constructor(redisClient: any);
+    acquire(waUserId: string, options?: ConcurrencyLeaseOptions): Promise<ConcurrencyLease>;
+    isLocked(waUserId: string, keyPrefix?: string): Promise<boolean>;
+}
+/**
+ * Factory helper to construct the appropriate lease service based on environment or connection.
+ */
+declare function createConcurrencyLeaseService(connection?: any): ConcurrencyLeaseService;
+
+interface FSMWorkerOptions {
+    connection: any;
+    queueName?: string;
+    resendQueueName?: string;
+    persistence: PersistenceAdapter;
+    flow: FlowDefinition;
+    flaresendClient: FlaresendClient;
+    concurrency?: number;
+    leaseService?: ConcurrencyLeaseService;
+    leaseOptions?: ConcurrencyLeaseOptions;
+    enableConcurrencyLease?: boolean;
+}
+/**
+ * Decoupled job processor function containing the core worker logic.
+ * This makes the FSM Worker extremely easy to test in isolation without requiring actual Redis.
+ */
+declare function processFSMJob(jobData: {
+    wamid: string;
+    waUserId: string;
+    messageText: string;
+    timestamp?: number;
+}, options: {
+    persistence: PersistenceAdapter;
+    flow: FlowDefinition;
+    flaresendClient: FlaresendClient;
+    resendQueue?: Queue;
+    leaseService?: ConcurrencyLeaseService;
+    leaseOptions?: ConcurrencyLeaseOptions;
+}): Promise<{
+    nextState: any;
+    sentReply: boolean;
+    result: TransitionResult;
+}>;
+/**
+ * Creates and registers a BullMQ Worker instance connected to the specified Redis connection.
+ * Also configures a companion resend queue and worker to gracefully handle delivery failures.
+ */
+declare function createFSMWorker(options: FSMWorkerOptions): Worker;
+
+interface TurnTrace {
+    id: string;
+    sessionId: string;
+    timestamp: number;
+    flowId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    rawInput: string;
+    matchedPattern: string;
+    outboundText: string | null;
+    retryCount: number;
+    status: "active" | "escalated" | "completed" | "abandoned";
+    contextSnapshot: Record<string, any>;
+    durationMs: number;
+}
+interface SessionTrace {
+    sessionId: string;
+    flowId: string;
+    startTime: number;
+    endTime: number;
+    turns: TurnTrace[];
+    finalStatus: "active" | "escalated" | "completed" | "abandoned";
+    totalRetries: number;
+}
+interface FlowMetrics {
+    totalSessions: number;
+    completedSessions: number;
+    escalatedSessions: number;
+    activeSessions: number;
+    containmentRate: number;
+    completionRate: number;
+    escalationRate: number;
+    avgTurnsPerSession: number;
+    totalRetries: number;
+    nodeStats: Record<string, {
+        visits: number;
+        retries: number;
+        dropOffs: number;
+        unhandledInputs: string[];
+        patternBreakdown: Record<string, number>;
+    }>;
+}
+declare class TraceCollector {
+    private traces;
+    private listeners;
+    constructor(initialTraces?: TurnTrace[]);
+    logTurn(turn: Omit<TurnTrace, "id" | "timestamp">): TurnTrace;
+    onTurn(listener: (turn: TurnTrace) => void): () => void;
+    getTraces(): TurnTrace[];
+    getSessions(): SessionTrace[];
+    computeMetrics(flow?: FlowDefinition): FlowMetrics;
+    clear(): void;
+}
+
+interface ScenarioTurnStep {
+    input: string;
+    expectedNodeId?: string;
+    expectedOutboundPattern?: string | RegExp;
+    expectedContext?: Record<string, any>;
+    expectEscalated?: boolean;
+    expectCompleted?: boolean;
+}
+interface ConversationScenario {
+    id: string;
+    name: string;
+    description?: string;
+    initialContext?: Record<string, any>;
+    steps: ScenarioTurnStep[];
+}
+interface StepEvaluationResult {
+    stepIndex: number;
+    input: string;
+    actualNodeId: string;
+    expectedNodeId?: string;
+    actualOutbound: string | null;
+    expectedOutboundPattern?: string | RegExp;
+    actualStatus: string;
+    actualContext: Record<string, any>;
+    passed: boolean;
+    failureReason?: string;
+}
+interface ScenarioResult {
+    scenarioId: string;
+    scenarioName: string;
+    passed: boolean;
+    stepResults: StepEvaluationResult[];
+    durationMs: number;
+    visitedNodeIds: string[];
+}
+interface EvaluationReport {
+    totalScenarios: number;
+    passedScenarios: number;
+    failedScenarios: number;
+    passRate: number;
+    nodeCoveragePercentage: number;
+    coveredNodeIds: string[];
+    uncoveredNodeIds: string[];
+    scenarioResults: ScenarioResult[];
+    totalDurationMs: number;
+}
+declare class Evaluator {
+    private flow;
+    constructor(flow: FlowDefinition);
+    runScenario(scenario: ConversationScenario): Promise<ScenarioResult>;
+    runSuite(scenarios: ConversationScenario[]): Promise<EvaluationReport>;
+}
+
+export { type ActionBranch, type ActionDefinition, type ActionDefinitionOptions, type ActionFunction, ActionNodeBuilder, AmbiguousSendError, type AvailableCommandsResult, Bot, CallbackPersistenceAdapter, type CallbackPersistenceAdapterOptions, CompileError, type CompiledMatcher, type ConcurrencyLease, type ConcurrencyLeaseOptions, type ConcurrencyLeaseService, ConcurrencyLockError, Context, type ConversationScenario, type ConversationState, type EvaluationReport, Evaluator, FSMEngine, type FSMWorkerOptions, FlaresendClient, type FlaresendClientOptions, FlaresendSendError, type FlowDefinition, type FlowMetrics, type FlowNode, FlowNodeBuilder, type GlobalTransition, GlobalTransitionBuilder, type GlobalTransitionOptions, type HandoffDefinition, HandoffNodeBuilder, type HandoffNodeOptions, type HandoffSession, IdempotencyService, InMemoryConcurrencyLeaseService, KnownNotSentError, type LegalCommandInfo, type LifecycleEventInfo, type LifecycleHook, type MatchResult, MongoosePersistenceAdapter, type NormalizedRequest, type NormalizedResponse, OptimisticConcurrencyError, type PersistenceAdapter, RedisConcurrencyLeaseService, type ScenarioResult, type ScenarioTurnStep, type SessionTrace, type StepEvaluationResult, TraceCollector, type Transition, type TransitionResult, type TurnTrace, type WebhookCoreOptions, type WebhookJob, type WebhookQueue, classifyFlaresendError, createConcurrencyLeaseService, createExpressAdapter, createFSMWorker, createFastifyAdapter, createLiteralMatcher, createRawHttpAdapter, expressAdapter, extractWebhookPayload, fastifyAdapter, handleWebhookCore, httpAdapter, matchesAny, processFSMJob, rawHttpAdapter, registerFlowDefinition, runConversationStep, verifyWebhookSignature };