@joshualelon/clawdbot-skill-flow 0.3.1 → 0.5.0

package/src/hooks/google-sheets.ts

@@ -0,0 +1,326 @@
+/**
+ * Google Sheets integration utilities for logging flow data
+ */
+
+import { google, sheets_v4 } from "googleapis";
+import type { FlowHooks, FlowSession } from "../types.js";
+import type { SheetsLogOptions, GoogleServiceAccountCredentials, HeaderMode } from "./types.js";
+import { withRetry } from "./common.js";
+
+/**
+ * Create a Google Sheets API client with authentication
+ */
+async function createSheetsClient(
+  credentials?: GoogleServiceAccountCredentials
+): Promise<sheets_v4.Sheets> {
+  // If credentials provided, use service account auth
+  if (credentials) {
+    const auth = new google.auth.GoogleAuth({
+      credentials: {
+        client_email: credentials.clientEmail,
+        private_key: credentials.privateKey,
+      },
+      scopes: ["https://www.googleapis.com/auth/spreadsheets"],
+    });
+
+    // GoogleAuth is compatible with the auth parameter expected by google.sheets()
+    // The typing is complex due to multiple auth types, but runtime behavior is correct
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return google.sheets({ version: "v4", auth: auth as any });
+  }
+
+  // Otherwise, use application default credentials (from environment)
+  const auth = new google.auth.GoogleAuth({
+    scopes: ["https://www.googleapis.com/auth/spreadsheets"],
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return google.sheets({ version: "v4", auth: auth as any });
+}
+
+/**
+ * Create a hook that logs captured variables to Google Sheets.
+ * Returns an onCapture hook function.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   onCapture: createSheetsLogger({
+ *     spreadsheetId: '1ABC...xyz',
+ *     worksheetName: 'Workouts',
+ *     columns: ['set1', 'set2', 'set3'],
+ *     includeMetadata: true
+ *   })
+ * };
+ * ```
+ */
+export function createSheetsLogger(
+  options: SheetsLogOptions
+): NonNullable<FlowHooks["onCapture"]> {
+  const {
+    spreadsheetId,
+    worksheetName = "Sheet1",
+    columns,
+    includeMetadata = true,
+    credentials,
+    headerMode = 'append',
+  } = options;
+
+  return async (variable: string, value: string | number, session: FlowSession) => {
+    try {
+      // Prepare row data
+      const row: Record<string, unknown> = {};
+
+      // Add metadata if requested
+      if (includeMetadata) {
+        row.timestamp = new Date().toISOString();
+        row.userId = session.senderId;
+        row.flowName = session.flowName;
+        row.channel = session.channel;
+      }
+
+      // Add all session variables (or filtered columns)
+      if (columns && columns.length > 0) {
+        // Only include specified columns
+        for (const col of columns) {
+          row[col] = session.variables[col] ?? "";
+        }
+      } else {
+        // Include all variables
+        Object.assign(row, session.variables);
+      }
+
+      // Also include the just-captured variable
+      row[variable] = value;
+
+      // Append to sheet with retry
+      await withRetry(
+        () => appendToSheet(spreadsheetId, worksheetName, [row], credentials, headerMode),
+        { maxAttempts: 3, delayMs: 1000, backoff: true }
+      );
+    } catch (error) {
+      // Enhanced error message with context
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(
+        `Failed to log to Google Sheets (spreadsheetId: ${spreadsheetId}, worksheet: ${worksheetName}): ${errorMessage}. ` +
+          `Check credentials, permissions, and API quotas. Flow continues without logging.`
+      );
+      // Don't throw - logging failures shouldn't break the flow
+    }
+  };
+}
+
+/**
+ * Low-level utility to append rows to a Google Sheet.
+ * Creates the worksheet if it doesn't exist, and adds headers on first write.
+ *
+ * @example
+ * ```ts
+ * await appendToSheet('1ABC...xyz', 'Workouts', [
+ *   { date: '2026-01-25', reps: 20, weight: 45 },
+ *   { date: '2026-01-26', reps: 22, weight: 45 }
+ * ], undefined, 'append');
+ * ```
+ */
+export async function appendToSheet(
+  spreadsheetId: string,
+  worksheetName: string,
+  rows: Array<Record<string, unknown>>,
+  credentials?: GoogleServiceAccountCredentials,
+  headerMode: HeaderMode = 'append'
+): Promise<void> {
+  if (rows.length === 0) {
+    return;
+  }
+
+  const sheets = await createSheetsClient(credentials);
+
+  // Ensure worksheet exists
+  await ensureWorksheetExists(sheets, spreadsheetId, worksheetName);
+
+  // Get existing data to check if we need to write headers
+  const existingData = await sheets.spreadsheets.values.get({
+    spreadsheetId,
+    range: `${worksheetName}!A1:ZZ1`, // Check first row for headers
+  });
+
+  const existingHeaders = existingData.data.values?.[0] || [];
+  const rowKeys = Object.keys(rows[0]!);
+
+  // Handle headers based on mode
+  if (existingHeaders.length === 0) {
+    // Empty sheet - always write headers
+    await sheets.spreadsheets.values.update({
+      spreadsheetId,
+      range: `${worksheetName}!A1`,
+      valueInputOption: "RAW",
+      requestBody: {
+        values: [rowKeys],
+      },
+    });
+  } else if (!arraysEqual(existingHeaders, rowKeys)) {
+    // Headers don't match - apply mode
+    switch (headerMode) {
+      case 'strict':
+        throw new Error(
+          `Header mismatch in sheet "${worksheetName}". ` +
+          `Expected: ${existingHeaders.join(', ')}. ` +
+          `Got: ${rowKeys.join(', ')}. ` +
+          `Set headerMode to 'append' or 'overwrite' to handle this.`
+        );
+
+      case 'append': {
+        // Find new columns not in existing headers
+        const newColumns = rowKeys.filter(key => !existingHeaders.includes(key));
+        if (newColumns.length > 0) {
+          // Append new columns to the right
+          const updatedHeaders = [...existingHeaders, ...newColumns];
+          await sheets.spreadsheets.values.update({
+            spreadsheetId,
+            range: `${worksheetName}!A1`,
+            valueInputOption: "RAW",
+            requestBody: {
+              values: [updatedHeaders],
+            },
+          });
+        }
+        break;
+      }
+
+      case 'overwrite':
+        // Replace headers completely
+        await sheets.spreadsheets.values.update({
+          spreadsheetId,
+          range: `${worksheetName}!A1`,
+          valueInputOption: "RAW",
+          requestBody: {
+            values: [rowKeys],
+          },
+        });
+        break;
+    }
+  }
+
+  // Convert rows to 2D array for Sheets API
+  const values = rows.map((row) => rowKeys.map((key) => row[key] ?? ""));
+
+  // Append data
+  await sheets.spreadsheets.values.append({
+    spreadsheetId,
+    range: `${worksheetName}!A:A`, // Append to column A (auto-detects next row)
+    valueInputOption: "RAW",
+    requestBody: {
+      values,
+    },
+  });
+}
+
+/**
+ * Query historical data from a Google Sheet.
+ * Useful for calculating statistics or generating dynamic buttons.
+ *
+ * @example
+ * ```ts
+ * const history = await querySheetHistory('1ABC...xyz', 'Workouts', {
+ *   flowName: 'pushups',
+ *   userId: 'user123',
+ *   dateRange: [new Date('2026-01-01'), new Date()]
+ * });
+ * ```
+ */
+export async function querySheetHistory(
+  spreadsheetId: string,
+  worksheetName: string,
+  filters?: {
+    flowName?: string;
+    userId?: string;
+    dateRange?: [Date, Date];
+  },
+  credentials?: GoogleServiceAccountCredentials
+): Promise<Array<Record<string, unknown>>> {
+  const sheets = await createSheetsClient(credentials);
+
+  // Get all data from worksheet
+  const response = await sheets.spreadsheets.values.get({
+    spreadsheetId,
+    range: `${worksheetName}!A:ZZ`,
+  });
+
+  const values = response.data.values || [];
+  if (values.length === 0) {
+    return [];
+  }
+
+  // First row is headers
+  const headers = values[0] as string[];
+  const rows = values.slice(1);
+
+  // Convert to array of objects
+  let data = rows.map((row: unknown[]) => {
+    const obj: Record<string, unknown> = {};
+    headers.forEach((header, index) => {
+      obj[header] = row[index] ?? "";
+    });
+    return obj;
+  });
+
+  // Apply filters
+  if (filters) {
+    if (filters.flowName) {
+      data = data.filter((row: Record<string, unknown>) => row.flowName === filters.flowName);
+    }
+    if (filters.userId) {
+      data = data.filter((row: Record<string, unknown>) => row.userId === filters.userId);
+    }
+    if (filters.dateRange) {
+      const [start, end] = filters.dateRange;
+      data = data.filter((row: Record<string, unknown>) => {
+        const timestamp = new Date(row.timestamp as string);
+        return timestamp >= start && timestamp <= end;
+      });
+    }
+  }
+
+  return data;
+}
+
+/**
+ * Ensure a worksheet exists, create it if not
+ */
+async function ensureWorksheetExists(
+  sheets: sheets_v4.Sheets,
+  spreadsheetId: string,
+  worksheetName: string
+): Promise<void> {
+  // Get spreadsheet metadata
+  const spreadsheet = await sheets.spreadsheets.get({ spreadsheetId });
+  const sheetExists = spreadsheet.data.sheets?.some(
+    (sheet: sheets_v4.Schema$Sheet) => sheet.properties?.title === worksheetName
+  );
+
+  if (!sheetExists) {
+    // Create new worksheet
+    await sheets.spreadsheets.batchUpdate({
+      spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            addSheet: {
+              properties: {
+                title: worksheetName,
+              },
+            },
+          },
+        ],
+      },
+    });
+  }
+}
+
+/**
+ * Check if two arrays are equal (for header comparison)
+ */
+function arraysEqual<T>(a: T[], b: T[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((val, index) => val === b[index]);
+}

package/src/hooks/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Hooks Utility Library
+ *
+ * Optional utilities for common workflow patterns.
+ * Import only what you need:
+ *
+ * @example
+ * ```ts
+ * // Import specific utilities
+ * import { createSheetsLogger } from '@joshualelon/clawdbot-skill-flow/hooks/google-sheets';
+ * import { createDynamicButtons } from '@joshualelon/clawdbot-skill-flow/hooks/dynamic-buttons';
+ *
+ * // Or import from main hooks export
+ * import { composeHooks, withRetry } from '@joshualelon/clawdbot-skill-flow/hooks';
+ * ```
+ */
+
+// Re-export types
+export type * from "./types.js";
+
+// Re-export common utilities
+export {
+  composeHooks,
+  withRetry,
+  validateEmail,
+  validateNumber,
+  validatePhone,
+  whenCondition,
+  debounceHook,
+  throttleHook,
+} from "./common.js";
+
+// Re-export Google Sheets utilities
+export { createSheetsLogger, appendToSheet, querySheetHistory } from "./google-sheets.js";
+
+// Re-export dynamic buttons utilities
+export { createDynamicButtons, getRecentAverage, generateButtonRange } from "./dynamic-buttons.js";
+
+// Re-export scheduling utilities
+export {
+  createScheduler,
+  scheduleNextSession,
+  checkCalendarConflicts,
+  findNextAvailableSlot,
+} from "./scheduling.js";

package/src/hooks/scheduling.ts

@@ -0,0 +1,259 @@
+/**
+ * Scheduling utilities for recurring workflows
+ */
+
+import { google, calendar_v3 } from "googleapis";
+import type { FlowHooks, FlowSession } from "../types.js";
+import type { ScheduleConfig, GoogleServiceAccountCredentials } from "./types.js";
+
+/**
+ * Create a hook that schedules the next workflow session after completion.
+ * Returns an onFlowComplete hook function.
+ *
+ * Note: Scheduling uses local server time. Ensure your server is in the correct timezone.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   onFlowComplete: createScheduler({
+ *     days: ['mon', 'wed', 'fri'],
+ *     time: '08:00',
+ *     calendarCheck: true,
+ *     calendarId: 'primary'
+ *   })
+ * };
+ * ```
+ */
+export function createScheduler(
+  config: ScheduleConfig
+): NonNullable<FlowHooks["onFlowComplete"]> {
+  const {
+    days = ["mon", "wed", "fri"],
+    time = "08:00",
+    calendarId = "primary",
+    credentials,
+    calendarCheck = false,
+    rescheduleOnConflict = false,
+  } = config;
+
+  return async (session: FlowSession): Promise<void> => {
+    try {
+      // Calculate next scheduled date
+      const nextDate = findNextScheduledDate(days, time);
+
+      if (!nextDate) {
+        console.warn("Unable to calculate next scheduled date");
+        return;
+      }
+
+      // Check for calendar conflicts if enabled
+      if (calendarCheck) {
+        const hasConflict = await checkCalendarConflicts(nextDate, 60, { calendarId, credentials });
+
+        if (hasConflict && rescheduleOnConflict) {
+          // Find alternative slot
+          const alternativeDate = await findNextAvailableSlot(
+            [nextDate],
+            60, // 60 minutes duration
+            { calendarId, credentials }
+          );
+
+          if (alternativeDate) {
+            await scheduleNextSession(
+              session.flowName,
+              session.senderId,
+              alternativeDate,
+              { calendarId, credentials }
+            );
+            return;
+          }
+        } else if (hasConflict) {
+          console.warn(
+            `Calendar conflict detected for ${nextDate.toISOString()}, not scheduling`
+          );
+          return;
+        }
+      }
+
+      // Schedule next session
+      await scheduleNextSession(session.flowName, session.senderId, nextDate, { calendarId, credentials });
+    } catch (error) {
+      // Enhanced error message with context
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(
+        `Failed to schedule next session for flow "${session.flowName}": ${errorMessage}. ` +
+          `Check calendar credentials and permissions.`
+      );
+      // Don't throw - scheduling failures shouldn't break the flow
+    }
+  };
+}
+
+/**
+ * Schedule the next workflow session for a user by creating a Google Calendar event.
+ *
+ * @example
+ * ```ts
+ * await scheduleNextSession('pushups', 'user123', new Date('2026-01-27T08:00:00Z'), {
+ *   calendarId: 'primary',
+ *   credentials: { clientEmail: '...', privateKey: '...' }
+ * });
+ * ```
+ */
+export async function scheduleNextSession(
+  flowName: string,
+  userId: string,
+  nextDate: Date,
+  options?: { calendarId?: string; credentials?: GoogleServiceAccountCredentials }
+): Promise<void> {
+  const calendar = await createCalendarClient(options?.credentials);
+  const calendarId = options?.calendarId || 'primary';
+
+  // Calculate end time (default 30 min duration)
+  const endDate = new Date(nextDate);
+  endDate.setMinutes(endDate.getMinutes() + 30);
+
+  await calendar.events.insert({
+    calendarId,
+    requestBody: {
+      summary: `${flowName} Workflow`,
+      start: { dateTime: nextDate.toISOString() },
+      end: { dateTime: endDate.toISOString() },
+      description: `Scheduled session for ${flowName} flow (user: ${userId})`
+    }
+  });
+}
+
+/**
+ * Check if there are calendar conflicts at the given time by querying Google Calendar.
+ *
+ * @example
+ * ```ts
+ * const hasConflict = await checkCalendarConflicts(
+ *   new Date('2026-01-27T08:00:00Z'),
+ *   60,
+ *   { calendarId: 'primary', credentials: { ... } }
+ * );
+ * ```
+ */
+export async function checkCalendarConflicts(
+  dateTime: Date,
+  duration = 60,
+  options?: { calendarId?: string; credentials?: GoogleServiceAccountCredentials }
+): Promise<boolean> {
+  const calendar = await createCalendarClient(options?.credentials);
+  const calendarId = options?.calendarId || 'primary';
+
+  const endTime = new Date(dateTime);
+  endTime.setMinutes(endTime.getMinutes() + duration);
+
+  const response = await calendar.events.list({
+    calendarId,
+    timeMin: dateTime.toISOString(),
+    timeMax: endTime.toISOString(),
+    singleEvents: true
+  });
+
+  return (response.data.items?.length || 0) > 0;
+}
+
+/**
+ * Find the next available time slot from a list of preferred dates by checking Google Calendar.
+ *
+ * @example
+ * ```ts
+ * const nextSlot = await findNextAvailableSlot(
+ *   [new Date('2026-01-27T08:00:00Z')],
+ *   60,
+ *   { calendarId: 'primary', credentials: { ... } }
+ * );
+ * ```
+ */
+export async function findNextAvailableSlot(
+  preferredDates: Date[],
+  duration: number,
+  options?: { calendarId?: string; credentials?: GoogleServiceAccountCredentials }
+): Promise<Date | null> {
+  for (const date of preferredDates) {
+    const hasConflict = await checkCalendarConflicts(date, duration, options);
+    if (!hasConflict) {
+      return date;
+    }
+  }
+  return null; // No free slots found
+}
+
+/**
+ * Find the next scheduled date based on day-of-week and time preferences.
+ * Uses local server time.
+ */
+function findNextScheduledDate(
+  days: string[],
+  time: string
+): Date | null {
+  const now = new Date();
+
+  // Parse target time (HH:MM format)
+  const [hours, minutes] = time.split(":").map(Number);
+  if (hours === undefined || minutes === undefined || Number.isNaN(hours) || Number.isNaN(minutes)) {
+    return null;
+  }
+
+  // Map day names to numbers (0=Sunday, 1=Monday, etc.)
+  const dayMap: Record<string, number> = {
+    sun: 0,
+    mon: 1,
+    tue: 2,
+    wed: 3,
+    thu: 4,
+    fri: 5,
+    sat: 6,
+  };
+
+  const targetDays = days.map((d) => dayMap[d.toLowerCase()]).filter((d): d is number => d !== undefined);
+
+  if (targetDays.length === 0) {
+    return null;
+  }
+
+  // Find next occurrence
+  for (let daysAhead = 1; daysAhead <= 14; daysAhead++) {
+    const candidate = new Date(now);
+    candidate.setDate(candidate.getDate() + daysAhead);
+    candidate.setHours(hours, minutes, 0, 0);
+
+    const dayOfWeek = candidate.getDay();
+
+    if (targetDays.includes(dayOfWeek)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Create a Google Calendar API client with authentication
+ */
+async function createCalendarClient(
+  credentials?: GoogleServiceAccountCredentials
+): Promise<calendar_v3.Calendar> {
+  if (credentials) {
+    const auth = new google.auth.GoogleAuth({
+      credentials: {
+        client_email: credentials.clientEmail,
+        private_key: credentials.privateKey,
+      },
+      scopes: ['https://www.googleapis.com/auth/calendar'],
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return google.calendar({ version: 'v3', auth: auth as any });
+  }
+
+  // Use application default credentials
+  const auth = new google.auth.GoogleAuth({
+    scopes: ['https://www.googleapis.com/auth/calendar'],
+  });
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return google.calendar({ version: 'v3', auth: auth as any });
+}

package/src/hooks/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Type definitions for hooks utility library
+ */
+
+import type { FlowSession, FlowHooks } from "../types.js";
+
+/**
+ * Google Sheets configuration
+ */
+export interface SheetsConfig {
+  spreadsheetId: string;
+  worksheetName?: string;
+  credentials?: GoogleServiceAccountCredentials;
+}
+
+export interface GoogleServiceAccountCredentials {
+  clientEmail: string;
+  privateKey: string;
+}
+
+export type HeaderMode = 'strict' | 'append' | 'overwrite';
+
+export interface SheetsLogOptions {
+  spreadsheetId: string;
+  worksheetName?: string;
+  columns?: string[]; // Variable names to log
+  includeMetadata?: boolean; // Add timestamp, userId, flowName
+  credentials?: GoogleServiceAccountCredentials;
+  headerMode?: HeaderMode; // How to handle header mismatches (default: 'append')
+}
+
+/**
+ * Dynamic buttons configuration
+ */
+export interface DynamicButtonsConfig {
+  spreadsheetId?: string; // Source for history (Google Sheets)
+  historyFile?: string; // Or use local .jsonl
+  variable: string; // Which variable to generate buttons for
+  strategy: "centered" | "progressive" | "range";
+  buttonCount?: number; // How many buttons (default: 5)
+  step?: number; // Increment between buttons
+}
+
+export type ButtonStrategy = "centered" | "progressive" | "range";
+
+/**
+ * Scheduling configuration
+ */
+export interface ScheduleConfig {
+  days?: string[]; // ['mon', 'wed', 'fri']
+  time?: string; // '08:00' (uses local server time)
+  calendarId?: string; // Google Calendar ID (default: 'primary')
+  credentials?: GoogleServiceAccountCredentials; // For calendar API access
+  calendarCheck?: boolean; // Check for conflicts
+  rescheduleOnConflict?: boolean;
+}
+
+/**
+ * Hook composer type - accepts multiple hooks and merges them
+ */
+export type HookFunction<T extends keyof FlowHooks> = NonNullable<FlowHooks[T]>;
+
+/**
+ * Condition function for conditional hooks
+ */
+export type ConditionFunction = (session: FlowSession) => boolean | Promise<boolean>;
+
+/**
+ * Retry configuration
+ */
+export interface RetryOptions {
+  maxAttempts?: number;
+  delayMs?: number;
+  backoff?: boolean; // Use exponential backoff
+  maxDelayMs?: number; // Maximum delay cap (default: 30000ms)
+}