@joshualelon/clawdbot-skill-flow 0.1.0

package/src/commands/flow-step.ts

@@ -0,0 +1,101 @@
+/**
+ * /flow-step command - Handle flow step transitions (called via Telegram callbacks)
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { loadFlow } from "../state/flow-store.js";
+import {
+  getSession,
+  getSessionKey,
+  updateSession,
+  deleteSession,
+} from "../state/session-store.js";
+import { saveFlowHistory } from "../state/history-store.js";
+import { processStep } from "../engine/executor.js";
+
+export function createFlowStepCommand(api: ClawdbotPluginApi) {
+  return async (args: {
+    args?: string;
+    senderId: string;
+    channel: string;
+  }) => {
+    const input = args.args?.trim();
+
+    if (!input) {
+      return {
+        text: "Error: Missing step parameters",
+      };
+    }
+
+    // Parse callback: "flowName stepId:value"
+    const parts = input.split(" ");
+    if (parts.length < 2) {
+      return {
+        text: "Error: Invalid step parameters",
+      };
+    }
+
+    const flowName = parts[0]!;
+    const stepData = parts.slice(1).join(" "); // Handle spaces in value
+    const colonIndex = stepData.indexOf(":");
+
+    if (colonIndex === -1) {
+      return {
+        text: "Error: Invalid step format (expected stepId:value)",
+      };
+    }
+
+    const stepId = stepData.substring(0, colonIndex);
+    const valueStr = stepData.substring(colonIndex + 1);
+
+    // Get active session
+    const sessionKey = getSessionKey(args.senderId, flowName);
+    const session = getSession(sessionKey);
+
+    if (!session) {
+      return {
+        text: `Session expired or not found.\n\nUse /flow-start ${flowName} to restart the flow.`,
+      };
+    }
+
+    // Load flow
+    const flow = await loadFlow(api, flowName);
+
+    if (!flow) {
+      deleteSession(sessionKey);
+      return {
+        text: `Flow "${flowName}" not found.`,
+      };
+    }
+
+    // Detect if value should be numeric
+    const value = /^\d+$/.test(valueStr) ? Number(valueStr) : valueStr;
+
+    // Process step transition
+    const result = processStep(api, flow, session, stepId, value);
+
+    // Update session or cleanup
+    if (result.complete) {
+      // Save to history
+      const finalSession = {
+        ...session,
+        variables: result.updatedVariables,
+      };
+      await saveFlowHistory(api, finalSession);
+
+      // Cleanup session
+      deleteSession(sessionKey);
+
+      api.logger.info(
+        `Completed flow "${flowName}" for user ${args.senderId}`
+      );
+    } else {
+      // Update session with new variables and current step
+      updateSession(sessionKey, {
+        variables: result.updatedVariables,
+      });
+    }
+
+    return result.reply;
+  };
+}

package/src/engine/executor.ts

@@ -0,0 +1,109 @@
+/**
+ * Main flow execution orchestrator
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import type { FlowMetadata, FlowSession, ReplyPayload } from "../types.js";
+import { renderStep } from "./renderer.js";
+import { executeTransition } from "./transitions.js";
+
+/**
+ * Start a flow from the beginning
+ */
+export function startFlow(
+  api: ClawdbotPluginApi,
+  flow: FlowMetadata,
+  session: FlowSession
+): ReplyPayload {
+  const firstStep = flow.steps[0];
+
+  if (!firstStep) {
+    return {
+      text: `Error: Flow "${flow.name}" has no steps`,
+    };
+  }
+
+  return renderStep(api, flow, firstStep, session, session.channel);
+}
+
+/**
+ * Process a step transition and return next step or completion message
+ */
+export function processStep(
+  api: ClawdbotPluginApi,
+  flow: FlowMetadata,
+  session: FlowSession,
+  stepId: string,
+  value: string | number
+): {
+  reply: ReplyPayload;
+  complete: boolean;
+  updatedVariables: Record<string, string | number>;
+} {
+  const result = executeTransition(api, flow, session, stepId, value);
+
+  // Handle errors
+  if (result.error) {
+    return {
+      reply: { text: result.message || result.error },
+      complete: false,
+      updatedVariables: result.variables,
+    };
+  }
+
+  // Handle completion
+  if (result.complete) {
+    const completionMessage = generateCompletionMessage(flow, result.variables);
+    return {
+      reply: { text: completionMessage },
+      complete: true,
+      updatedVariables: result.variables,
+    };
+  }
+
+  // Render next step
+  if (!result.nextStepId) {
+    return {
+      reply: { text: "Error: No next step found" },
+      complete: false,
+      updatedVariables: result.variables,
+    };
+  }
+
+  const nextStep = flow.steps.find((s) => s.id === result.nextStepId);
+  if (!nextStep) {
+    return {
+      reply: { text: `Error: Step ${result.nextStepId} not found` },
+      complete: false,
+      updatedVariables: result.variables,
+    };
+  }
+
+  const updatedSession = { ...session, variables: result.variables };
+  const reply = renderStep(api, flow, nextStep, updatedSession, session.channel);
+
+  return {
+    reply,
+    complete: false,
+    updatedVariables: result.variables,
+  };
+}
+
+/**
+ * Generate completion message
+ */
+function generateCompletionMessage(
+  flow: FlowMetadata,
+  variables: Record<string, string | number>
+): string {
+  let message = `✅ Flow "${flow.name}" completed!\n\n`;
+
+  if (Object.keys(variables).length > 0) {
+    message += "Summary:\n";
+    for (const [key, value] of Object.entries(variables)) {
+      message += `• ${key}: ${value}\n`;
+    }
+  }
+
+  return message;
+}

package/src/engine/renderer.ts

@@ -0,0 +1,119 @@
+/**
+ * Flow step rendering for different channel types
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import type {
+  FlowMetadata,
+  FlowStep,
+  FlowSession,
+  ReplyPayload,
+} from "../types.js";
+import { normalizeButton } from "../validation.js";
+
+/**
+ * Interpolate variables in message text
+ */
+function interpolateVariables(
+  text: string,
+  variables: Record<string, string | number>
+): string {
+  return text.replace(/\{\{(\w+)\}\}/g, (match, varName) => {
+    const value = variables[varName];
+    return value !== undefined ? String(value) : match;
+  });
+}
+
+/**
+ * Render step for Telegram (with inline keyboard)
+ */
+function renderTelegram(
+  flowName: string,
+  step: FlowStep,
+  variables: Record<string, string | number>
+): ReplyPayload {
+  const message = interpolateVariables(step.message, variables);
+
+  if (!step.buttons || step.buttons.length === 0) {
+    return { text: message };
+  }
+
+  const buttons = step.buttons.map((btn, idx) =>
+    normalizeButton(btn, idx)
+  );
+
+  // Detect if all buttons are numeric (for grid layout)
+  const allNumeric = buttons.every((btn) => typeof btn.value === "number");
+
+  let keyboard: Array<{ text: string; callback_data: string }[]>;
+
+  if (allNumeric && buttons.length > 2) {
+    // 2-column grid for numeric buttons
+    keyboard = [];
+    for (let i = 0; i < buttons.length; i += 2) {
+      const row = buttons.slice(i, i + 2).map((btn) => ({
+        text: btn.text,
+        callback_data: `/flow-step ${flowName} ${step.id}:${btn.value}`,
+      }));
+      keyboard.push(row);
+    }
+  } else {
+    // Single column for text buttons
+    keyboard = buttons.map((btn) => [
+      {
+        text: btn.text,
+        callback_data: `/flow-step ${flowName} ${step.id}:${btn.value}`,
+      },
+    ]);
+  }
+
+  return {
+    text: message,
+    buttons: keyboard,
+  };
+}
+
+/**
+ * Render step for fallback channels (text-based)
+ */
+function renderFallback(
+  step: FlowStep,
+  variables: Record<string, string | number>
+): ReplyPayload {
+  const message = interpolateVariables(step.message, variables);
+
+  if (!step.buttons || step.buttons.length === 0) {
+    return { text: message };
+  }
+
+  const buttons = step.buttons.map((btn, idx) =>
+    normalizeButton(btn, idx)
+  );
+
+  const buttonList = buttons
+    .map((btn, idx) => `${idx + 1}. ${btn.text}`)
+    .join("\n");
+
+  return {
+    text: `${message}\n\n${buttonList}\n\nReply with the number of your choice.`,
+  };
+}
+
+/**
+ * Render a flow step
+ */
+export function renderStep(
+  _api: ClawdbotPluginApi,
+  flow: FlowMetadata,
+  step: FlowStep,
+  session: FlowSession,
+  channel: string
+): ReplyPayload {
+  // Channel-specific rendering
+  if (channel === "telegram") {
+    return renderTelegram(flow.name, step, session.variables);
+  }
+
+  // Fallback for all other channels
+  return renderFallback(step, session.variables);
+}

package/src/engine/transitions.ts

@@ -0,0 +1,160 @@
+/**
+ * Flow step transition logic with validation and conditional branching
+ */
+
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import type {
+  FlowMetadata,
+  FlowStep,
+  FlowSession,
+  TransitionResult,
+} from "../types.js";
+import { normalizeButton, validateInput } from "../validation.js";
+
+/**
+ * Evaluate condition against session variables
+ */
+function evaluateCondition(
+  condition: FlowStep["condition"],
+  variables: Record<string, string | number>
+): boolean {
+  if (!condition) {
+    return false;
+  }
+
+  const value = variables[condition.variable];
+
+  if (value === undefined) {
+    return false;
+  }
+
+  // Check equals
+  if (condition.equals !== undefined) {
+    return value === condition.equals;
+  }
+
+  // Check greater than
+  if (condition.greaterThan !== undefined) {
+    const numValue =
+      typeof value === "number" ? value : Number(value);
+    return !isNaN(numValue) && numValue > condition.greaterThan;
+  }
+
+  // Check less than
+  if (condition.lessThan !== undefined) {
+    const numValue =
+      typeof value === "number" ? value : Number(value);
+    return !isNaN(numValue) && numValue < condition.lessThan;
+  }
+
+  // Check contains (for strings)
+  if (condition.contains !== undefined) {
+    return String(value).includes(condition.contains);
+  }
+
+  return false;
+}
+
+/**
+ * Find next step ID based on transition rules
+ */
+function findNextStep(
+  step: FlowStep,
+  value: string | number,
+  variables: Record<string, string | number>
+): string | undefined {
+  // 1. Check button-specific next
+  if (step.buttons && step.buttons.length > 0) {
+    const buttons = step.buttons.map((btn, idx) =>
+      normalizeButton(btn, idx)
+    );
+    const matchingButton = buttons.find((btn) => btn.value === value);
+    if (matchingButton?.next) {
+      return matchingButton.next;
+    }
+  }
+
+  // 2. Check conditional branching
+  if (step.condition && evaluateCondition(step.condition, variables)) {
+    return step.condition.next;
+  }
+
+  // 3. Use default next
+  return step.next;
+}
+
+/**
+ * Execute step transition
+ */
+export function executeTransition(
+  _api: ClawdbotPluginApi,
+  flow: FlowMetadata,
+  session: FlowSession,
+  stepId: string,
+  value: string | number
+): TransitionResult {
+  // Find current step
+  const step = flow.steps.find((s) => s.id === stepId);
+
+  if (!step) {
+    return {
+      variables: session.variables,
+      complete: false,
+      error: `Step ${stepId} not found`,
+    };
+  }
+
+  // Convert value to string for validation
+  const valueStr = String(value);
+
+  // Validate input if required
+  if (step.validate) {
+    const validation = validateInput(valueStr, step.validate);
+    if (!validation.valid) {
+      return {
+        variables: session.variables,
+        complete: false,
+        error: validation.error,
+        message: validation.error,
+      };
+    }
+  }
+
+  // Capture variable if specified
+  const updatedVariables = { ...session.variables };
+  if (step.capture) {
+    // Convert to number if validation type is number
+    if (step.validate === "number") {
+      updatedVariables[step.capture] = Number(value);
+    } else {
+      updatedVariables[step.capture] = valueStr;
+    }
+  }
+
+  // Find next step
+  const nextStepId = findNextStep(step, value, updatedVariables);
+
+  // If no next step, flow is complete
+  if (!nextStepId) {
+    return {
+      variables: updatedVariables,
+      complete: true,
+    };
+  }
+
+  // Verify next step exists
+  const nextStep = flow.steps.find((s) => s.id === nextStepId);
+  if (!nextStep) {
+    return {
+      variables: updatedVariables,
+      complete: false,
+      error: `Next step ${nextStepId} not found`,
+    };
+  }
+
+  return {
+    nextStepId,
+    variables: updatedVariables,
+    complete: false,
+  };
+}

package/src/examples/onboarding.json

@@ -0,0 +1,41 @@
+{
+  "name": "onboarding",
+  "description": "User onboarding wizard with email validation",
+  "version": "1.0.0",
+  "author": "Clawdbot Team",
+  "triggers": {
+    "manual": true
+  },
+  "steps": [
+    {
+      "id": "welcome",
+      "message": "👋 Welcome! Let's get you set up.\n\nWhat's your name?",
+      "capture": "name",
+      "next": "preferences"
+    },
+    {
+      "id": "preferences",
+      "message": "Nice to meet you, {{name}}!\n\nWhat are you interested in?",
+      "buttons": [
+        "Productivity",
+        "Fitness",
+        "Learning",
+        "Entertainment"
+      ],
+      "capture": "interests",
+      "next": "email"
+    },
+    {
+      "id": "email",
+      "message": "What's your email address?",
+      "capture": "email",
+      "validate": "email",
+      "next": "confirm"
+    },
+    {
+      "id": "confirm",
+      "message": "Perfect! Here's what we have:\n\n• Name: {{name}}\n• Interests: {{interests}}\n• Email: {{email}}\n\nReady to get started?",
+      "buttons": ["Yes, let's go!", "Start over"]
+    }
+  ]
+}

package/src/examples/pushups.json

@@ -0,0 +1,49 @@
+{
+  "name": "pushups",
+  "description": "4-set pushup workout tracker",
+  "version": "1.0.0",
+  "author": "Clawdbot Team",
+  "triggers": {
+    "manual": true,
+    "cron": "45 13 * * *"
+  },
+  "steps": [
+    {
+      "id": "reminder",
+      "message": "🏋️ Time for your daily pushup workout!\n\nReady to start?",
+      "buttons": ["Yes, let's go!", "Skip today"],
+      "next": "set1"
+    },
+    {
+      "id": "set1",
+      "message": "Set 1: How many pushups did you do?",
+      "buttons": [20, 25, 30, 35, 40],
+      "capture": "set1",
+      "validate": "number",
+      "next": "set2"
+    },
+    {
+      "id": "set2",
+      "message": "Great! Set 2: How many pushups?",
+      "buttons": [20, 25, 30, 35, 40],
+      "capture": "set2",
+      "validate": "number",
+      "next": "set3"
+    },
+    {
+      "id": "set3",
+      "message": "Awesome! Set 3: How many?",
+      "buttons": [20, 25, 30, 35, 40],
+      "capture": "set3",
+      "validate": "number",
+      "next": "set4"
+    },
+    {
+      "id": "set4",
+      "message": "Final set! How many pushups?",
+      "buttons": [20, 25, 30, 35, 40],
+      "capture": "set4",
+      "validate": "number"
+    }
+  ]
+}

package/src/examples/survey.json

@@ -0,0 +1,41 @@
+{
+  "name": "survey",
+  "description": "Customer satisfaction survey with conditional branching",
+  "version": "1.0.0",
+  "author": "Clawdbot Team",
+  "triggers": {
+    "manual": true
+  },
+  "steps": [
+    {
+      "id": "satisfaction",
+      "message": "How satisfied are you with our service?",
+      "buttons": ["⭐", "⭐⭐", "⭐⭐⭐", "⭐⭐⭐⭐", "⭐⭐⭐⭐⭐"],
+      "capture": "satisfaction",
+      "next": "nps"
+    },
+    {
+      "id": "nps",
+      "message": "On a scale of 0-10, how likely are you to recommend us?",
+      "buttons": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+      "capture": "nps",
+      "validate": "number",
+      "condition": {
+        "variable": "nps",
+        "greaterThan": 7,
+        "next": "positive-feedback"
+      },
+      "next": "negative-feedback"
+    },
+    {
+      "id": "positive-feedback",
+      "message": "Great to hear! 🎉 What did you love most about our service?",
+      "capture": "feedback"
+    },
+    {
+      "id": "negative-feedback",
+      "message": "We're sorry to hear that. What can we improve?",
+      "capture": "feedback"
+    }
+  ]
+}