@q1k-oss/btree-workflows 0.0.1

package/behaviour-tree-workflows-landing/vite.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      // Map library source imports
+      '@btree': path.resolve(__dirname, '../src'),
+      // Stub out Node.js / Temporal modules that can't run in the browser
+      '@temporalio/workflow': path.resolve(__dirname, 'src/stubs/temporal-workflow.ts'),
+      '@temporalio/activity': path.resolve(__dirname, 'src/stubs/temporal-activity.ts'),
+      'fs/promises': path.resolve(__dirname, 'src/stubs/fs.ts'),
+      'fs': path.resolve(__dirname, 'src/stubs/fs.ts'),
+      'path': path.resolve(__dirname, 'src/stubs/path.ts'),
+      '@activepieces/piece-google-sheets': path.resolve(__dirname, 'src/stubs/activepieces.ts'),
+      '@activepieces/pieces-framework': path.resolve(__dirname, 'src/stubs/activepieces.ts'),
+    },
+    // Ensure dependencies imported by the library source are resolved
+    // from the playground's node_modules (parent has no node_modules)
+    dedupe: ['js-yaml', 'zod'],
+  },
+  // Allow Vite to serve files from the parent src/ directory
+  server: {
+    fs: {
+      allow: ['.', '../src'],
+    },
+  },
+  // Force Rollup to resolve bare imports from the playground's node_modules
+  // even when processing files from the parent directory
+  optimizeDeps: {
+    include: ['js-yaml', 'zod'],
+  },
+  define: {
+    'process.env': '{}',
+    'process.versions': '{}',
+    'process.platform': '"browser"',
+  },
+});

package/demo-google-sheets.ts

@@ -0,0 +1,181 @@
+/**
+ * Demo: Google Sheets Integration with btree
+ *
+ * This demo shows how to use the IntegrationAction node to interact
+ * with Google Sheets via Active Pieces.
+ *
+ * Prerequisites:
+ * 1. OAuth connection established via controlplane
+ * 2. Controlplane running at localhost:5001
+ */
+
+import {
+  Registry,
+  registerStandardNodes,
+  loadTreeFromYaml,
+  ScopedBlackboard,
+  NodeStatus,
+} from "./src/index.js";
+import type { IntegrationContext, TokenProvider } from "./src/integrations/integration-action.js";
+
+// Token provider that fetches from controlplane
+const controlplaneTokenProvider: TokenProvider = async (context, provider, connectionId) => {
+  const integrationContext = context as IntegrationContext;
+
+  const response = await fetch("http://localhost:5001/internal/integrations/token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-internal-api-key": process.env.INTERNAL_API_KEY || "dev-internal-key-12345",
+    },
+    body: JSON.stringify({
+      tenantId: integrationContext.tenantId,
+      userId: integrationContext.userId,
+      providerName: provider,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get token: ${error}`);
+  }
+
+  const data = await response.json() as { accessToken: string };
+  return { access_token: data.accessToken };
+};
+
+async function main() {
+  console.log("🚀 Google Sheets Integration Demo\n");
+
+  // Create registry with standard nodes
+  const registry = new Registry();
+  registerStandardNodes(registry);
+
+  // First, let's create a test spreadsheet
+  console.log("Step 1: Creating a test spreadsheet...\n");
+
+  const createSheetYaml = `
+type: IntegrationAction
+id: create-sheet
+props:
+  provider: google
+  action: create-spreadsheet
+  inputs:
+    title: "BTree Demo Sheet - \${bb.timestamp}"
+    sheetName: "Orders"
+`;
+
+  const createNode = loadTreeFromYaml(createSheetYaml, registry);
+  const blackboard = new ScopedBlackboard();
+  blackboard.set("timestamp", new Date().toISOString().slice(0, 19));
+
+  const context: IntegrationContext = {
+    blackboard,
+    treeRegistry: registry,
+    timestamp: Date.now(),
+    deltaTime: 0,
+    tokenProvider: controlplaneTokenProvider,
+    tenantId: process.env.DEV_TENANT_ID || "00000000-0000-0000-0000-000000000000",
+    userId: process.env.DEV_USER_ID || "00000000-0000-0000-0000-000000000001",
+  };
+
+  const createStatus = await createNode.tick(context);
+
+  if (createStatus !== NodeStatus.SUCCESS) {
+    console.log("❌ Failed to create spreadsheet");
+    console.log("Error:", createNode.lastError);
+    return;
+  }
+
+  const createResult = blackboard.get("create-sheet.result") as { id?: string; spreadsheetId?: string } | undefined;
+  console.log("✅ Spreadsheet created!");
+  console.log("   Result:", JSON.stringify(createResult, null, 2));
+
+  const spreadsheetId = createResult?.id || createResult?.spreadsheetId;
+  if (!spreadsheetId) {
+    console.log("❌ No spreadsheet ID returned");
+    return;
+  }
+
+  // Store spreadsheet ID for next steps
+  blackboard.set("spreadsheetId", spreadsheetId);
+  console.log(`\n📊 Spreadsheet URL: https://docs.google.com/spreadsheets/d/${spreadsheetId}`);
+
+  // Test insert_row with correct Active Pieces format
+  console.log("\nStep 2: Inserting rows (array mode)...\n");
+
+  // Active Pieces expects { values: { values: [...] } } for first_row_headers=false
+  const insertRowYaml = `
+type: Sequence
+id: insert-data
+children:
+  - type: IntegrationAction
+    id: insert-header
+    props:
+      provider: google
+      action: insert_row
+      inputs:
+        spreadsheetId: "\${bb.spreadsheetId}"
+        sheetId: 0
+        first_row_headers: false
+        as_string: true
+        values:
+          values:
+            - "Order ID"
+            - "Customer"
+            - "Amount"
+            - "Status"
+  - type: IntegrationAction
+    id: insert-row-1
+    props:
+      provider: google
+      action: insert_row
+      inputs:
+        spreadsheetId: "\${bb.spreadsheetId}"
+        sheetId: 0
+        first_row_headers: false
+        as_string: true
+        values:
+          values:
+            - "ORD-001"
+            - "John Doe"
+            - "99.99"
+            - "Completed"
+  - type: IntegrationAction
+    id: insert-row-2
+    props:
+      provider: google
+      action: insert_row
+      inputs:
+        spreadsheetId: "\${bb.spreadsheetId}"
+        sheetId: 0
+        first_row_headers: false
+        as_string: true
+        values:
+          values:
+            - "ORD-002"
+            - "Jane Smith"
+            - "149.50"
+            - "Pending"
+`;
+
+  const insertNode = loadTreeFromYaml(insertRowYaml, registry);
+  const insertStatus = await insertNode.tick(context);
+
+  if (insertStatus === NodeStatus.SUCCESS) {
+    console.log("✅ Rows inserted successfully!");
+  } else {
+    console.log("⚠️ Row insertion failed (see gap analysis doc)");
+    console.log("   Error:", insertNode.lastError);
+  }
+
+  console.log("\n✅ Demo complete!");
+  console.log("\n📋 Summary:");
+  console.log("   - OAuth connection: Working");
+  console.log("   - Token retrieval: Working");
+  console.log("   - Google Sheets API: Working");
+  console.log(`   - Created spreadsheet: ${spreadsheetId}`);
+  console.log(`\n📊 View: https://docs.google.com/spreadsheets/d/${spreadsheetId}`);
+}
+
+main().catch(console.error);

package/demo-runtime-variables.ts

@@ -0,0 +1,174 @@
+/**
+ * Demo: Runtime Variables & Input Parameters
+ *
+ * This demo showcases the unified variable resolution system:
+ *
+ * Variable Syntax:
+ * - ${input.key}  - Workflow input parameters (immutable)
+ * - ${bb.key}     - Blackboard values (mutable runtime state)
+ * - ${env.KEY}    - Environment variables
+ * - ${param.key}  - Test data parameters
+ * - ${key}        - Shorthand for ${bb.key} (backward compatible)
+ *
+ * Script Node Proxies:
+ * - $input.key    - Read-only workflow input
+ * - $env.KEY      - Read-only allowed environment variables
+ * - $bb.key       - Read/write blackboard
+ *
+ * SubTree Parameters:
+ * - params: {}    - Values passed to subtree (supports variable resolution)
+ * - outputs: []   - Keys exported back to parent after execution
+ *
+ * Run with:
+ *   TAX_RATE=0.10 BASE_DISCOUNT=0.05 npx tsx demo-runtime-variables.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import {
+  Registry,
+  registerStandardNodes,
+  loadTreeFromYaml,
+  BehaviorTree,
+  NodeStatus,
+} from "./src/index.js";
+
+async function main() {
+  console.log("=".repeat(60));
+  console.log("  Runtime Variables & Input Parameters Demo");
+  console.log("=".repeat(60));
+  console.log();
+
+  // Show environment configuration
+  console.log("Environment Configuration:");
+  console.log(`  TAX_RATE:      ${process.env.TAX_RATE || "0.08 (default)"}`);
+  console.log(`  BASE_DISCOUNT: ${process.env.BASE_DISCOUNT || "0 (default)"}`);
+  console.log();
+
+  // 1. Setup registry
+  const registry = new Registry();
+  registerStandardNodes(registry);
+
+  // 2. Load YAML workflow files from workflows/ directory
+  const workflowsDir = path.join(import.meta.dirname, "workflows");
+  console.log(`Loading workflows from: ${workflowsDir}`);
+  console.log();
+
+  // Load order-processor subtree
+  const orderProcessorYaml = fs.readFileSync(
+    path.join(workflowsDir, "order-processor.yaml"),
+    "utf-8"
+  );
+  const orderProcessorTree = loadTreeFromYaml(orderProcessorYaml, registry);
+  const orderProcessorBT = new BehaviorTree(orderProcessorTree);
+  registry.registerTree("order-processor", orderProcessorBT, "order-processor.yaml");
+  console.log("  Loaded: order-processor.yaml (SubTree)");
+
+  // Load main workflow
+  const mainWorkflowYaml = fs.readFileSync(
+    path.join(workflowsDir, "process-order-workflow.yaml"),
+    "utf-8"
+  );
+  const mainWorkflowTree = loadTreeFromYaml(mainWorkflowYaml, registry);
+  const mainWorkflowBT = new BehaviorTree(mainWorkflowTree);
+  console.log("  Loaded: process-order-workflow.yaml (Main)");
+  console.log();
+
+  // 3. Convert to workflow function (Temporal-compatible)
+  const workflow = mainWorkflowBT.toWorkflow();
+
+  // 4. Define workflow input (passed at runtime)
+  const workflowInput = {
+    orderId: "ORD-2024-0042",
+    customerId: "CUST-001", // John Doe - gold tier
+    items: [
+      { name: "Widget Pro", price: 49.99, quantity: 2 },
+      { name: "Gadget Plus", price: 29.99, quantity: 1 },
+      { name: "Super Cable", price: 9.99, quantity: 3 },
+    ],
+  };
+
+  console.log("Workflow Input:");
+  console.log(`  orderId:    ${workflowInput.orderId}`);
+  console.log(`  customerId: ${workflowInput.customerId}`);
+  console.log(`  items:      ${workflowInput.items.length} items`);
+  for (const item of workflowInput.items) {
+    console.log(`    - ${item.name}: $${item.price} x ${item.quantity}`);
+  }
+  console.log();
+
+  // 5. Execute workflow
+  console.log("-".repeat(60));
+  console.log("Workflow Execution:");
+  console.log("-".repeat(60));
+  console.log();
+
+  const result = await workflow({
+    input: workflowInput,
+    treeRegistry: registry,
+    sessionId: "demo-session-001",
+  });
+
+  console.log();
+  console.log("-".repeat(60));
+  console.log("Workflow Result:");
+  console.log("-".repeat(60));
+  console.log();
+
+  console.log(`Status: ${result.status}`);
+  console.log();
+
+  if (result.status === NodeStatus.SUCCESS) {
+    const output = result.output;
+
+    console.log("Customer:");
+    const customer = output.customer as Record<string, unknown>;
+    console.log(`  Name:  ${customer?.name}`);
+    console.log(`  Email: ${customer?.email}`);
+    console.log(`  Tier:  ${customer?.tier}`);
+    console.log();
+
+    console.log("Order Result (from SubTree):");
+    const orderResult = output.orderResult as Record<string, unknown>;
+    console.log(`  Order ID:   ${orderResult?.orderId}`);
+    console.log(`  Items:      ${orderResult?.itemCount}`);
+    console.log(`  Subtotal:   $${orderResult?.subtotal}`);
+    console.log(`  Tax Rate:   ${((orderResult?.taxRate as number) * 100).toFixed(0)}%`);
+    console.log(`  Tax:        $${orderResult?.tax}`);
+    console.log(`  Total:      $${orderResult?.total}`);
+    console.log();
+
+    console.log("Final Order (with discount):");
+    const finalOrder = output.finalOrder as Record<string, unknown>;
+    console.log(`  Discount:   ${finalOrder?.discountPercent}% (${customer?.tier} tier + base)`);
+    console.log(`  Savings:    $${finalOrder?.discountAmount}`);
+    console.log(`  Final:      $${finalOrder?.finalTotal}`);
+    console.log();
+
+    console.log("Notification:");
+    const notification = output.notification as Record<string, unknown>;
+    console.log(`  To:      ${notification?.to}`);
+    console.log(`  Subject: ${notification?.subject}`);
+    console.log(`  Sent:    ${notification?.sentAt}`);
+  }
+
+  console.log();
+  console.log("=".repeat(60));
+  console.log("  Demo Complete!");
+  console.log("=".repeat(60));
+  console.log();
+  console.log("Key Features Demonstrated:");
+  console.log("  1. YAML workflows loaded from files (production-like)");
+  console.log("  2. ${input.key} - Immutable workflow input parameters");
+  console.log("  3. ${bb.key} - Mutable blackboard state");
+  console.log("  4. ${env.KEY} - Environment variable access");
+  console.log("  5. SubTree params - Pass values to subtrees with resolution");
+  console.log("  6. SubTree outputs - Export values back to parent");
+  console.log("  7. Script $input/$env/$bb - Full access in JavaScript");
+  console.log("  8. allowedEnvVars - Security-conscious env access");
+  console.log();
+  console.log("Try with different env vars:");
+  console.log("  TAX_RATE=0.15 BASE_DISCOUNT=0.10 npx tsx demo-runtime-variables.ts");
+}
+
+main().catch(console.error);

package/demo-template.ts

@@ -0,0 +1,208 @@
+/**
+ * Demo: Using GoogleSheets.InsertRow Template
+ *
+ * This demonstrates using templates for friendly Google Sheets integration.
+ * The template handles data transformation automatically.
+ */
+
+import {
+  Registry,
+  registerStandardNodes,
+  loadTreeFromYaml,
+  loadTemplatesFromDirectory,
+  ScopedBlackboard,
+  NodeStatus,
+} from "./src/index.js";
+import type { IntegrationContext, TokenProvider } from "./src/integrations/integration-action.js";
+import * as path from "path";
+
+// Token provider that fetches from controlplane
+const controlplaneTokenProvider: TokenProvider = async (context, provider) => {
+  const integrationContext = context as IntegrationContext;
+
+  const response = await fetch("http://localhost:5001/internal/integrations/token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-internal-api-key": process.env.INTERNAL_API_KEY || "dev-internal-key-12345",
+    },
+    body: JSON.stringify({
+      tenantId: integrationContext.tenantId,
+      userId: integrationContext.userId,
+      providerName: provider,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get token: ${error}`);
+  }
+
+  const data = await response.json() as { accessToken: string };
+  return { access_token: data.accessToken };
+};
+
+async function main() {
+  console.log("===========================================");
+  console.log("  Google Sheets Template Demo");
+  console.log("===========================================\n");
+
+  // 1. Setup registry with standard nodes
+  const registry = new Registry();
+  registerStandardNodes(registry);
+
+  // 2. Load templates
+  console.log("Loading templates...\n");
+  const templatesDir = path.join(import.meta.dirname, "templates/google-sheets");
+  await loadTemplatesFromDirectory(registry, {
+    templatesDir,
+    idPrefix: "GoogleSheets."
+  });
+
+  // 3. Create context
+  const blackboard = new ScopedBlackboard();
+  const context: IntegrationContext = {
+    blackboard,
+    treeRegistry: registry,
+    timestamp: Date.now(),
+    deltaTime: 0,
+    tokenProvider: controlplaneTokenProvider,
+    tenantId: process.env.DEV_TENANT_ID || "00000000-0000-0000-0000-000000000000",
+    userId: process.env.DEV_USER_ID || "00000000-0000-0000-0000-000000000001",
+  };
+
+  // 4. First, create a spreadsheet (direct action)
+  console.log("Step 1: Creating spreadsheet...\n");
+
+  const timestamp = new Date().toISOString().slice(0, 19);
+  const createYaml = `
+type: IntegrationAction
+id: create-sheet
+props:
+  provider: google
+  action: create-spreadsheet
+  inputs:
+    title: "Template Demo - ${timestamp}"
+    sheetName: "Orders"
+`;
+
+  const createNode = loadTreeFromYaml(createYaml, registry);
+  const createStatus = await createNode.tick(context);
+
+  if (createStatus !== NodeStatus.SUCCESS) {
+    console.log("Failed to create spreadsheet:", createNode.lastError);
+    return;
+  }
+
+  const createResult = blackboard.get("create-sheet.result") as { id?: string };
+  const spreadsheetId = createResult?.id;
+  console.log(`Created spreadsheet: ${spreadsheetId}`);
+  console.log(`URL: https://docs.google.com/spreadsheets/d/${spreadsheetId}\n`);
+
+  // 5. Use TEMPLATE to insert rows with friendly syntax
+  // The template reads from _tpl.* keys, transforms, and calls IntegrationAction
+  console.log("Step 2: Inserting rows using template...\n");
+
+  // Build workflow that uses SubTree to call template
+  // Each insert: set _tpl.* inputs → call SubTree → template executes
+  const insertYaml = `
+type: Sequence
+id: insert-orders
+children:
+  # --- Insert Header Row ---
+  - type: CodeExecution
+    id: set-header-inputs
+    props:
+      language: javascript
+      code: |
+        setBB('tpl_spreadsheet', '${spreadsheetId}');
+        setBB('tpl_sheet', 0);
+        setBB('tpl_values', ['Order ID', 'Customer', 'Amount', 'Status']);
+
+  - type: SubTree
+    id: insert-header
+    props:
+      treeId: "GoogleSheets.insert-row"
+
+  - type: LogMessage
+    id: log-header-done
+    props:
+      message: "Header row inserted"
+      level: info
+
+  # --- Insert Data Row 1 ---
+  - type: CodeExecution
+    id: set-row1-inputs
+    props:
+      language: javascript
+      code: |
+        setBB('tpl_spreadsheet', '${spreadsheetId}');
+        setBB('tpl_sheet', 0);
+        setBB('tpl_values', {
+          'Order ID': 'ORD-001',
+          'Customer': 'John Doe',
+          'Amount': '99.99',
+          'Status': 'Completed'
+        });
+
+  - type: SubTree
+    id: insert-row-1
+    props:
+      treeId: "GoogleSheets.insert-row"
+
+  - type: LogMessage
+    id: log-row1-done
+    props:
+      message: "Row 1 inserted"
+      level: info
+
+  # --- Insert Data Row 2 ---
+  - type: CodeExecution
+    id: set-row2-inputs
+    props:
+      language: javascript
+      code: |
+        setBB('tpl_spreadsheet', '${spreadsheetId}');
+        setBB('tpl_sheet', 0);
+        setBB('tpl_values', {
+          'Order ID': 'ORD-002',
+          'Customer': 'Jane Smith',
+          'Amount': '149.50',
+          'Status': 'Pending'
+        });
+
+  - type: SubTree
+    id: insert-row-2
+    props:
+      treeId: "GoogleSheets.insert-row"
+
+  - type: LogMessage
+    id: log-row2-done
+    props:
+      message: "Row 2 inserted"
+      level: info
+`;
+
+  const insertNode = loadTreeFromYaml(insertYaml, registry);
+  const insertStatus = await insertNode.tick(context);
+
+  if (insertStatus === NodeStatus.SUCCESS) {
+    console.log("\nAll rows inserted successfully!\n");
+  } else {
+    console.log("\nRow insertion failed:", insertNode.lastError);
+  }
+
+  // 6. Summary
+  console.log("===========================================");
+  console.log("  Demo Complete!");
+  console.log("===========================================");
+  console.log(`\nSpreadsheet: https://docs.google.com/spreadsheets/d/${spreadsheetId}`);
+  console.log("\nWhat we demonstrated:");
+  console.log("  - Template loaded from YAML file");
+  console.log("  - Friendly input format (object with column names)");
+  console.log("  - Template transformed to Active Pieces format");
+  console.log("  - SubTree for reusable workflow execution");
+  console.log("  - LogMessage for debugging");
+}
+
+main().catch(console.error);