@joshualelon/clawdbot-skill-flow 2.2.0 → 2.3.0

package/README.md

@@ -403,7 +403,47 @@ Each step can declare what actions to execute:
 
 #### Hooks File Structure
 
-Action functions are exported as **named exports** from your hooks file. Plugin utilities are available via the `api.hooks` object:
+Action functions are exported as **named exports** from your hooks file. All actions receive an `api` parameter as their final argument - plugin utilities are available via `api.hooks`.
+
+> **Note:** No imports needed! Just destructure what you need from `api.hooks`.
+
+**Action Signatures:**
+
+```typescript
+// Fetch actions - retrieve data before rendering
+export async function myFetch(session: FlowSession, api: EnhancedPluginApi) {
+  const { querySheetHistory } = api.hooks;
+  return { variableName: value };
+}
+
+// BeforeRender actions - modify step before display
+export async function myBeforeRender(step: FlowStep, session: FlowSession, api: EnhancedPluginApi) {
+  const { generateButtonRange } = api.hooks;
+  return { ...step, buttons: [...] };
+}
+
+// AfterCapture actions - side effects after capturing input
+export async function myAfterCapture(variable: string, value: string | number, session: FlowSession, api: EnhancedPluginApi) {
+  const { appendToSheet } = api.hooks;
+  await appendToSheet('spreadsheet-id', { [variable]: value });
+}
+
+// Create a new spreadsheet (typically in a fetch action)
+export async function createWorkoutLog(session, api) {
+  const { createSpreadsheet } = api.hooks;
+
+  const { spreadsheetId, spreadsheetUrl } = await createSpreadsheet({
+    title: `${session.flowName} Log - ${new Date().getFullYear()}`,
+    worksheetName: 'Sessions',
+    headers: ['timestamp', 'userId', 'set1', 'set2', 'set3', 'set4', 'total'],
+    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID // Optional: move to specific folder
+  });
+
+  return { spreadsheetId, spreadsheetUrl };
+}
+```
+
+**Complete Example:**
 
 ```javascript
 // ~/.clawdbot/flows/pushups/hooks.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshualelon/clawdbot-skill-flow",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "description": "Multi-step workflow orchestration plugin for Clawdbot",
   "keywords": [

package/src/hooks/google-sheets.ts

@@ -284,6 +284,155 @@ export async function querySheetHistory(
   return data;
 }
 
+/**
+ * Create a new Google Spreadsheet with optional initial data
+ *
+ * @param options - Configuration for spreadsheet creation
+ * @returns Object containing spreadsheetId and spreadsheetUrl
+ *
+ * @example
+ * ```ts
+ * // Create a simple spreadsheet
+ * const { spreadsheetId, spreadsheetUrl } = await createSpreadsheet({
+ *   title: 'Pushups Log 2026',
+ *   worksheetName: 'Sessions'
+ * });
+ *
+ * // Create with initial headers and move to folder
+ * const result = await createSpreadsheet({
+ *   title: 'Pushups Log 2026',
+ *   worksheetName: 'Sessions',
+ *   headers: ['timestamp', 'userId', 'set1', 'set2', 'set3', 'set4', 'total'],
+ *   folderId: '1ABC...xyz'
+ * });
+ * ```
+ */
+export async function createSpreadsheet(options: {
+  title: string;
+  worksheetName?: string;
+  headers?: string[];
+  folderId?: string;
+  credentials?: GoogleServiceAccountCredentials;
+}): Promise<{ spreadsheetId: string; spreadsheetUrl: string }> {
+  const {
+    title,
+    worksheetName = 'Sheet1',
+    headers,
+    folderId,
+    credentials,
+  } = options;
+
+  const sheets = await createSheetsClient(credentials);
+
+  // Create the spreadsheet
+  const createResponse = await sheets.spreadsheets.create({
+    requestBody: {
+      properties: {
+        title,
+        locale: 'en_US',
+        timeZone: 'America/Chicago', // Default to CT, users can change
+      },
+      sheets: [
+        {
+          properties: {
+            title: worksheetName,
+            gridProperties: {
+              rowCount: 1000,
+              columnCount: 26,
+              frozenRowCount: headers ? 1 : 0, // Freeze header row if headers provided
+            },
+          },
+        },
+      ],
+    },
+  });
+
+  const spreadsheetId = createResponse.data.spreadsheetId;
+  const spreadsheetUrl = createResponse.data.spreadsheetUrl;
+
+  if (!spreadsheetId || !spreadsheetUrl) {
+    throw new Error('Failed to create spreadsheet: missing ID or URL');
+  }
+
+  // Add headers if provided
+  if (headers && headers.length > 0) {
+    await sheets.spreadsheets.values.update({
+      spreadsheetId,
+      range: `${worksheetName}!A1`,
+      valueInputOption: 'RAW',
+      requestBody: {
+        values: [headers],
+      },
+    });
+
+    // Bold the header row
+    await sheets.spreadsheets.batchUpdate({
+      spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            repeatCell: {
+              range: {
+                sheetId: 0,
+                startRowIndex: 0,
+                endRowIndex: 1,
+              },
+              cell: {
+                userEnteredFormat: {
+                  textFormat: {
+                    bold: true,
+                  },
+                },
+              },
+              fields: 'userEnteredFormat.textFormat.bold',
+            },
+          },
+        ],
+      },
+    });
+  }
+
+  // Move to folder if specified
+  if (folderId) {
+    // Create Drive API client with same auth
+    let driveAuth;
+    if (credentials) {
+      driveAuth = new google.auth.GoogleAuth({
+        credentials: {
+          client_email: credentials.clientEmail,
+          private_key: credentials.privateKey,
+        },
+        scopes: ['https://www.googleapis.com/auth/drive.file'],
+      });
+    } else {
+      driveAuth = new google.auth.GoogleAuth({
+        scopes: ['https://www.googleapis.com/auth/drive.file'],
+      });
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const drive = google.drive({ version: 'v3', auth: driveAuth as any });
+
+    // Get current parents (usually root)
+    const file = await drive.files.get({
+      fileId: spreadsheetId,
+      fields: 'parents',
+    });
+
+    const previousParents = file.data.parents?.join(',');
+
+    // Move to new folder
+    await drive.files.update({
+      fileId: spreadsheetId,
+      addParents: folderId,
+      removeParents: previousParents,
+      fields: 'id, parents',
+    });
+  }
+
+  return { spreadsheetId, spreadsheetUrl };
+}
+
 /**
  * Ensure a worksheet exists, create it if not
  */

package/src/hooks/index.ts

@@ -31,7 +31,7 @@ export {
 } from "./common.js";
 
 // Re-export Google Sheets utilities
-export { createSheetsLogger, appendToSheet, querySheetHistory } from "./google-sheets.js";
+export { createSheetsLogger, appendToSheet, querySheetHistory, createSpreadsheet } from "./google-sheets.js";
 
 // Re-export dynamic buttons utilities
 export { createDynamicButtons, getRecentAverage, generateButtonRange } from "./dynamic-buttons.js";