100x Workflow Compiler

A TypeScript-to-JSON compiler for building browser automation workflows that run in Chrome extensions. This project provides a type-safe, developer-friendly way to create complex browser automation workflows while maintaining compatibility with Chrome's security restrictions.

🚀 Overview

The 100x Workflow Compiler transforms TypeScript workflow definitions into JSON that can be executed by Chrome extension service workers. This approach provides:

• Type Safety: Full TypeScript support with IntelliSense and compile-time checking
• Developer Experience: Fluent API with method chaining for intuitive workflow creation
• Chrome Compatibility: Outputs pure JSON that bypasses Chrome's dynamic code execution restrictions
• Modularity: Reusable components, parameters, and sub-workflows
• Extensibility: Easy to add new action types and workflow patterns
• 60% Less Code: Compared to writing raw JSON workflows

📋 Table of Contents

• Installation
• Quick Start
• Core Concepts
• API Reference
• Examples
• Architecture
• Testing
• Contributing
• Roadmap

🔧 Installation

# Using pnpm (recommended)
pnpm install @100x-bot/workflow-compiler

# Using npm
npm install @100x-bot/workflow-compiler

# Using yarn
yarn add @100x-bot/workflow-compiler

🎯 Quick Start

Running Workflows with CLI

The 100x Workflow Compiler includes a CLI tool to execute workflows directly:

# Build the project first
pnpm build

# Run a TypeScript workflow (use CSS selectors, not @selector references)
pnpm compile run examples/google-search-css.workflow.ts --extension /path/to/chrome-extension

# Run with parameters
pnpm compile run examples/simple-test.workflow.ts \
  --extension /path/to/chrome-extension \
  --params '{"message": "Custom message", "waitTime": "5"}'

# Run a JSON workflow
pnpm compile run dist/workflows/google-search.json \
  --extension /path/to/chrome-extension

# Set environment variables for convenience
export CHROME_EXTENSION_PATH=/path/to/chrome-extension
export TEST_AUTH_TOKEN=your-auth-token  # Optional
export CHROME_USER_DATA_DIR=/path/to/chrome-profile  # Optional

# Then run without flags
pnpm compile run examples/google-search.workflow.ts

# Download the latest Chrome extension from Chrome Web Store
pnpm compile download-extension

# Run workflow with auto-download (if CHROME_EXTENSION_PATH not set)
pnpm compile run examples/google-search.workflow.ts
# Extension will be automatically downloaded on first run

CLI Options

• -p, --params <json>: Pass parameters as JSON string
• -e, --extension <path>: Path to Chrome extension (or set CHROME_EXTENSION_PATH)
• -t, --token <token>: Authentication token (or set TEST_AUTH_TOKEN)
• -u, --user-data <dir>: Chrome user data directory (or set CHROME_USER_DATA_DIR)
• --headless: Run in headless mode (experimental)

Chrome Extension Management

The CLI can automatically download the latest 100xBot Chrome extension:

# Download extension manually
pnpm compile download-extension
pnpm compile download-extension -o /custom/path  # Custom output directory
pnpm compile download-extension -f               # Force re-download

# Auto-download when running workflows
# If CHROME_EXTENSION_PATH is not set, the extension will be downloaded automatically
pnpm compile run workflow.ts

Downloaded extensions are cached in the system temp directory and reused across runs.

Building Workflows

import { workflow, actions, param } from '@100x-bot/workflow-compiler';

// Create a simple workflow
const myWorkflow = workflow('example-workflow')
  .title('Example Workflow')
  .params({
    searchQuery: param.string('Search Query', { 
      defaultValue: 'TypeScript' 
    })
  })
  .step(
    actions.navigate('https://google.com'),
    actions.typeText('input[name="q"]', '@searchQuery@'),
    actions.keyPress('Enter'),
    actions.waitForSelector('#search')
  )
  .step(
    actions.extractData({
      results: {
        selector: '.g',
        multiple: true,
        data: {
          title: 'h3',
          url: { selector: 'a', attribute: 'href' },
          description: '.VwiC3b'
        }
      }
    }, 'searchResults')
  )
  .output({
    results: '{{searchResults.results}}'
  });

// Compile to JSON
const json = myWorkflow.compile();
console.log(json);

🏗️ Core Concepts

Workflows

Workflows are the top-level container for automation logic. They consist of:

• Parameters: Input values that can be referenced throughout the workflow
• State: Mutable data that persists across steps
• Steps: Sequential groups of actions
• Context: Metadata about the workflow's purpose and requirements
• Output: Data mapping for workflow results

Actions

Actions are the atomic units of browser automation:

// Navigation
actions.navigate('https://example.com')
actions.goBack()
actions.refreshPage()

// Interaction
actions.click('#button')
actions.typeText('#input', 'Hello')
actions.selectDropdown('#select', 'option1')

// Waiting
actions.waitForSeconds(2)
actions.waitForSelector('.loaded')
actions.waitForText('Success')

// Data extraction
actions.extractData({ title: 'h1' }, 'pageData')
actions.extractList('.item', { name: '.title' }, 'items')

// Control flow
actions.conditionalAction('{{state.isLoggedIn}}', [...])
actions.loop('@items@', 'item', [...])
actions.tryAction([...try], [...catch])

Parameters

Parameters allow workflows to accept input:

.params({
  // String parameter
  username: param.string('Username', { required: true }),
  
  // Number parameter
  maxResults: param.number('Max Results', { defaultValue: '10' }),
  
  // Boolean parameter
  includeImages: param.boolean('Include Images', { defaultValue: 'false' }),
  
  // Array parameter
  urls: param.array('URLs to Process', { defaultValue: '[]' }),
  
  // Object parameter
  config: param.object('Configuration', { 
    defaultValue: '{"timeout": 5000}' 
  })
})

State Management

State allows data persistence across workflow steps:

.state({
  processedCount: { type: 'number', default: 0 },
  results: { type: 'array', default: [] }
})
.step(
  actions.updateState({ 
    processedCount: '{{state.processedCount + 1}}' 
  })
)

📚 API Reference

WorkflowBuilder

workflow(name?: string): WorkflowBuilder

// Methods
.title(title: string): this
.version(version: string): this
.use(...components: string[]): this
.selectors(...selectors: string[]): this
.params(params: Record<string, InputParameter>): this
.state(state: Record<string, any>): this
.step(...actions: WorkflowAction[]): this
.context(context: WorkflowContext): this
.output(output: Record<string, any>): this
.build(): Workflow
.compile(): string

ActionBuilder

All 32 action types are available through the actions object:

// Browser Navigation
actions.navigate(url: string)
actions.click(selector: string)
actions.typeText(selector: string, text: string)
// ... and 29 more action types

ParamBuilder

param.string(label: string, options?: Partial<InputParameter>)
param.number(label: string, options?: Partial<InputParameter>)
param.boolean(label: string, options?: Partial<InputParameter>)
param.array(label: string, options?: Partial<InputParameter>)
param.object(label: string, options?: Partial<InputParameter>)

💡 Examples

LinkedIn Lead Generation

const linkedInWorkflow = workflow('linkedin-leads')
  .title('LinkedIn Lead Generation')
  .use('linkedin-auth')
  .selectors('linkedin')
  .params({
    searchQuery: param.string('Search Query', {
      defaultValue: 'CEO startup San Francisco'
    }),
    maxProfiles: param.number('Max Profiles', { defaultValue: '50' })
  })
  .step(
    actions.navigate('https://linkedin.com/search/results/people/'),
    actions.typeText('@linkedin.search.input', '@searchQuery@'),
    actions.keyPress('Enter')
  )
  .step(
    actions.paginate({
      nextSelector: '@linkedin.pagination.next',
      maxPages: 5,
      actions: [
        actions.extractList('.search-result', {
          profileUrl: { selector: 'a', attribute: 'href' },
          name: '.name',
          title: '.title'
        }, 'profiles')
      ]
    })
  )
  .output({
    profiles: '{{profiles}}'
  });

E-commerce Price Monitor

const priceMonitor = workflow('price-monitor')
  .title('Price Monitor')
  .params({
    products: param.array('Products', {
      defaultValue: JSON.stringify([
        { url: 'https://amazon.com/dp/B001', targetPrice: 99.99 }
      ])
    })
  })
  .step(
    actions.loop('@products@', 'product', [
      actions.navigate('{{product.url}}'),
      actions.extractData({
        price: { selector: '.price', transform: 'parseFloat' }
      }, 'priceData'),
      actions.conditionalAction(
        '{{priceData.price <= product.targetPrice}}',
        [actions.alert('Price dropped!')]
      )
    ])
  );

🏛️ Architecture

Design Principles

1. Type Safety First: Every workflow element is strongly typed
2. Builder Pattern: Fluent API for intuitive workflow construction
3. Immutability: Each builder method returns a new instance
4. Extensibility: Easy to add new action types and patterns
5. Chrome Compatibility: Output is pure JSON, no dynamic code

Project Structure

100x-workflows/
├── src/
│   ├── builders/
│   │   ├── workflow-builder.ts    # Main workflow builder
│   │   ├── action-builder.ts      # Action creation methods
│   │   └── param-builder.ts       # Parameter builders
│   ├── types/
│   │   └── workflow.ts            # TypeScript type definitions
│   └── index.ts                   # Public API exports
├── tests/
│   ├── unit/                      # Unit tests for builders
│   ├── integration/               # Integration tests
│   ├── snapshots/                 # JSON output snapshots
│   ├── validation/                # Schema validation tests
│   └── e2e/                       # End-to-end scenarios
└── docs/                          # Additional documentation

Chrome Extension Integration

The compiled JSON workflows are executed by a Chrome extension's service worker:

// In Chrome extension service worker
const workflowJson = await fetch('workflow.json').then(r => r.json());
const engine = new WorkflowEngine();
const results = await engine.execute(workflowJson, parameters);

🧪 Testing

The project includes comprehensive test coverage (>99%):

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

# Run specific test suite
pnpm test tests/unit/
pnpm test tests/integration/

# Update snapshots
pnpm vitest -u

Test Categories

• Unit Tests: Individual builder methods
• Integration Tests: Builder interactions
• Snapshot Tests: JSON output consistency
• Validation Tests: Schema and error handling
• E2E Tests: Real-world scenarios

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/100x/workflow-compiler.git

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

🗺️ Roadmap

See TODO.md for the detailed roadmap and upcoming features.

Upcoming Features

• Visual workflow editor
• Runtime type validation
• Workflow debugging tools
• Performance optimizations
• Additional action types
• Workflow marketplace

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Built for the 100x engineering community
• Inspired by Playwright, Puppeteer, and Selenium
• Designed for Chrome extension developers

For more detailed information, see:

• Architecture Guide
• API Documentation
• Chrome Extension Guide
• Migration Guide