machinaos 0.0.1

package/docs-MachinaOs/nodes/schedulers.mdx

@@ -0,0 +1,316 @@
+---
+title: Schedulers & Triggers
+description: Start workflows on schedules, timers, and manual triggers
+---
+
+# Schedulers & Triggers
+
+Control when and how workflows start execution.
+
+## Available Nodes
+
+| Node | Type | Purpose |
+|------|------|---------|
+| Workflow Trigger | Trigger | Manual workflow start |
+| Cron Scheduler | Trigger | Run on cron schedule |
+| Timer | Action | Delay execution |
+| Python Executor | Action | Run Python code |
+
+---
+
+## Workflow Trigger
+
+Manually start a workflow with the Run button.
+
+### Use Cases
+
+- Testing workflows during development
+- On-demand execution
+- Entry point for manual processes
+
+### Output
+
+```json
+{
+  "triggered_at": "2024-01-15T10:30:00Z",
+  "trigger_type": "manual"
+}
+```
+
+<Info>
+Every workflow needs at least one trigger node to start execution.
+</Info>
+
+---
+
+## Cron Scheduler
+
+Run workflows on a schedule using cron expressions.
+
+### Parameters
+
+<ParamField path="cronExpression" type="string" required>
+  Cron expression defining the schedule
+</ParamField>
+
+<ParamField path="timezone" type="string" default="UTC">
+  Timezone for schedule execution
+</ParamField>
+
+### Cron Expression Format
+
+```
+* * * * *
+│ │ │ │ │
+│ │ │ │ └── Day of week (0-7, Sun=0 or 7)
+│ │ │ └──── Month (1-12)
+│ │ └────── Day of month (1-31)
+│ └──────── Hour (0-23)
+└────────── Minute (0-59)
+```
+
+### Common Expressions
+
+| Expression | Description |
+|------------|-------------|
+| `* * * * *` | Every minute |
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour |
+| `0 0 * * *` | Daily at midnight |
+| `0 9 * * 1-5` | Weekdays at 9am |
+| `0 0 1 * *` | First day of month |
+| `0 12 * * 0` | Sundays at noon |
+
+### Output
+
+```json
+{
+  "triggered_at": "2024-01-15T09:00:00Z",
+  "trigger_type": "cron",
+  "expression": "0 9 * * *",
+  "next_run": "2024-01-16T09:00:00Z"
+}
+```
+
+### Example: Daily Report
+
+```
+[Cron (0 9 * * *)] --> [HTTP Request] --> [AI Summary] --> [WhatsApp Send]
+                        (fetch data)                         (send report)
+```
+
+---
+
+## Timer
+
+Add a delay between nodes.
+
+### Parameters
+
+<ParamField path="delay" type="number" required>
+  Delay duration
+</ParamField>
+
+<ParamField path="unit" type="select" default="seconds">
+  Time unit: seconds, minutes, hours
+</ParamField>
+
+### Use Cases
+
+- Rate limiting API calls
+- Waiting for external processes
+- Scheduling sequential actions
+
+### Example: Rate-Limited API Calls
+
+```
+[For Each Item] --> [HTTP Request] --> [Timer (1s)] --> [Next Item]
+```
+
+### Output
+
+```json
+{
+  "delayed": true,
+  "duration_ms": 5000,
+  "completed_at": "2024-01-15T10:30:05Z"
+}
+```
+
+---
+
+## Python Executor
+
+Run custom Python code within workflows.
+
+### Parameters
+
+<ParamField path="code" type="code" required>
+  Python code to execute
+</ParamField>
+
+### Available Variables
+
+| Variable | Description |
+|----------|-------------|
+| `input_data` | Data from connected input node |
+| `output` | Dictionary to set as node output |
+
+### Example: Data Processing
+
+```python
+# Access input data
+message = input_data.get("text", "")
+
+# Process
+word_count = len(message.split())
+has_question = "?" in message
+
+# Set output
+output = {
+    "word_count": word_count,
+    "has_question": has_question,
+    "summary": f"Message has {word_count} words"
+}
+```
+
+### Example: Conditional Logic
+
+```python
+level = input_data.get("battery_level", 100)
+is_charging = input_data.get("is_charging", False)
+
+if level < 20 and not is_charging:
+    output = {
+        "action": "alert",
+        "message": f"Low battery: {level}%"
+    }
+else:
+    output = {
+        "action": "none"
+    }
+```
+
+### Example: API Response Formatting
+
+```python
+import json
+
+# Parse response
+data = input_data.get("data", {})
+items = data.get("items", [])
+
+# Format for output
+formatted = []
+for item in items:
+    formatted.append({
+        "name": item.get("name"),
+        "price": f"${item.get('price', 0):.2f}"
+    })
+
+output = {
+    "count": len(formatted),
+    "items": formatted
+}
+```
+
+### Available Libraries
+
+The Python executor includes common libraries:
+- `json` - JSON parsing
+- `datetime` - Date/time handling
+- `re` - Regular expressions
+- `math` - Mathematical functions
+
+<Warning>
+Code runs in a sandboxed environment. File system and network access are restricted.
+</Warning>
+
+---
+
+## Combining Schedulers
+
+### Schedule with Delay
+
+```
+[Cron (hourly)] --> [HTTP Request] --> [Timer (5s)] --> [HTTP Request #2]
+```
+
+### Multiple Schedules
+
+Deploy workflows with different schedules:
+
+```
+Workflow 1: [Cron (daily)] --> [Daily Report]
+Workflow 2: [Cron (hourly)] --> [Hourly Check]
+Workflow 3: [Webhook] --> [On-Demand Action]
+```
+
+---
+
+## Workflow States
+
+After deployment, trigger nodes show their state:
+
+| State | Color | Description |
+|-------|-------|-------------|
+| Idle | Default | Waiting for next trigger |
+| Waiting | Cyan | Actively waiting for event |
+| Running | Purple | Workflow executing |
+
+---
+
+## Tips
+
+<Tip>
+Test cron expressions at [crontab.guru](https://crontab.guru) before deploying.
+</Tip>
+
+<Tip>
+Use **Python Executor** for conditional logic instead of multiple workflow branches.
+</Tip>
+
+<Tip>
+Add **Timer** nodes when calling rate-limited APIs repeatedly.
+</Tip>
+
+<Warning>
+Cron schedules are in **UTC** by default. Set timezone if needed.
+</Warning>
+
+---
+
+## Troubleshooting
+
+<Accordion title="Cron not triggering">
+  - Verify workflow is **deployed** (not just saved)
+  - Check cron expression syntax
+  - Ensure timezone is correct
+  - Check server logs for errors
+</Accordion>
+
+<Accordion title="Python code fails">
+  - Check for syntax errors
+  - Verify `input_data` has expected fields
+  - Use `try/except` for error handling
+  - Print debug info with `print()` (shows in logs)
+</Accordion>
+
+<Accordion title="Timer not working">
+  - Ensure delay value is positive
+  - Check unit (seconds vs minutes)
+  - Verify node is connected properly
+</Accordion>
+
+---
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Webhooks" icon="webhook" href="/nodes/webhooks">
+    Trigger workflows via HTTP
+  </Card>
+  <Card title="WhatsApp" icon="whatsapp" href="/nodes/whatsapp">
+    Message-triggered workflows
+  </Card>
+</CardGroup>

package/docs-MachinaOs/nodes/webhooks.mdx

@@ -0,0 +1,330 @@
+---
+title: Webhooks & HTTP
+description: HTTP requests and webhook handling nodes
+---
+
+# Webhooks & HTTP
+
+Make HTTP requests to external APIs and receive incoming webhooks.
+
+## Available Nodes
+
+| Node | Type | Purpose |
+|------|------|---------|
+| HTTP Request | Action | Make outgoing HTTP calls |
+| Webhook Trigger | Trigger | Receive incoming HTTP requests |
+| Webhook Response | Action | Send custom response to webhook caller |
+
+---
+
+## HTTP Request
+
+Make HTTP requests to external APIs and services.
+
+### Parameters
+
+<ParamField path="url" type="string" required>
+  The URL to request. Supports template variables.
+</ParamField>
+
+<ParamField path="method" type="select" default="GET">
+  HTTP method: GET, POST, PUT, DELETE, PATCH
+</ParamField>
+
+<ParamField path="headers" type="json">
+  Request headers as JSON object
+</ParamField>
+
+<ParamField path="body" type="string">
+  Request body (for POST, PUT, PATCH)
+</ParamField>
+
+<ParamField path="timeout" type="number" default="30">
+  Request timeout in seconds
+</ParamField>
+
+### Output
+
+```json
+{
+  "status": 200,
+  "statusText": "OK",
+  "headers": {
+    "content-type": "application/json"
+  },
+  "data": {
+    "result": "response data"
+  }
+}
+```
+
+### Examples
+
+**GET Request:**
+```
+URL: https://api.example.com/users/{{input.user_id}}
+Method: GET
+Headers: {"Authorization": "Bearer {{input.token}}"}
+```
+
+**POST Request:**
+```
+URL: https://api.example.com/orders
+Method: POST
+Headers: {"Content-Type": "application/json"}
+Body: {"product": "{{input.product}}", "quantity": {{input.qty}}}
+```
+
+**External API Integration:**
+```
+URL: https://api.openweathermap.org/data/2.5/weather?q={{input.city}}&appid=YOUR_KEY
+Method: GET
+```
+
+---
+
+## Webhook Trigger
+
+Receive incoming HTTP requests at a dynamic endpoint.
+
+### Parameters
+
+<ParamField path="path" type="string" required>
+  The webhook path (e.g., "orders" creates /webhook/orders)
+</ParamField>
+
+<ParamField path="method" type="select" default="POST">
+  HTTP method filter: GET, POST, PUT, DELETE, PATCH, or ANY
+</ParamField>
+
+<ParamField path="authentication" type="select" default="none">
+  Auth method: none, basic, bearer, api_key
+</ParamField>
+
+### Webhook URL
+
+Your webhook will be available at:
+```
+http://localhost:3010/webhook/{path}
+```
+
+For production:
+```
+https://your-domain.com/webhook/{path}
+```
+
+### Output
+
+```json
+{
+  "method": "POST",
+  "path": "/webhook/orders",
+  "headers": {
+    "content-type": "application/json",
+    "user-agent": "curl/7.68.0"
+  },
+  "query": {
+    "source": "website"
+  },
+  "body": {
+    "order_id": "12345",
+    "items": ["item1", "item2"]
+  },
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+### Authentication Options
+
+| Type | Description | Header |
+|------|-------------|--------|
+| None | No authentication | - |
+| Basic | Username:password base64 | `Authorization: Basic ...` |
+| Bearer | Token authentication | `Authorization: Bearer ...` |
+| API Key | Custom API key | `X-API-Key: ...` |
+
+---
+
+## Webhook Response
+
+Send a custom response back to the webhook caller.
+
+### Parameters
+
+<ParamField path="statusCode" type="number" default="200">
+  HTTP status code to return
+</ParamField>
+
+<ParamField path="body" type="string">
+  Response body. Supports template variables.
+</ParamField>
+
+<ParamField path="contentType" type="select" default="application/json">
+  Content-Type header: application/json, text/plain, text/html
+</ParamField>
+
+### Example Responses
+
+**Success Response:**
+```
+Status Code: 200
+Body: {"success": true, "message": "Order received", "id": "{{generated.id}}"}
+Content Type: application/json
+```
+
+**Error Response:**
+```
+Status Code: 400
+Body: {"error": "Invalid request", "details": "{{validation.error}}"}
+Content Type: application/json
+```
+
+**HTML Response:**
+```
+Status Code: 200
+Body: <html><body><h1>Thank you!</h1></body></html>
+Content Type: text/html
+```
+
+---
+
+## Common Workflows
+
+### API Endpoint
+
+Create a simple API endpoint:
+
+```
+[Webhook Trigger] --> [Python Executor] --> [Webhook Response]
+     (path: api)        (process data)       (return result)
+```
+
+**Test:**
+```bash
+curl -X POST http://localhost:3010/webhook/api \
+  -H "Content-Type: application/json" \
+  -d '{"action": "calculate", "value": 100}'
+```
+
+### Third-Party Integration
+
+Receive events from external services:
+
+```
+[Webhook Trigger] --> [HTTP Request] --> [WhatsApp Send]
+   (stripe/github)     (fetch details)     (notify admin)
+```
+
+### Data Pipeline
+
+Forward data to multiple destinations:
+
+```
+[Webhook Trigger] --> [HTTP Request #1] (Database API)
+                  |
+                  --> [HTTP Request #2] (Analytics)
+                  |
+                  --> [WhatsApp Send] (Notification)
+```
+
+### AI-Powered API
+
+Create an AI endpoint:
+
+```
+[Webhook Trigger] --> [OpenAI Chat] --> [Webhook Response]
+```
+
+**Prompt:** `{{webhookTrigger.body.prompt}}`
+
+**Response:** `{{openaiChatModel.response}}`
+
+---
+
+## Testing Webhooks
+
+### Using curl
+
+```bash
+# GET request
+curl http://localhost:3010/webhook/test
+
+# POST with JSON
+curl -X POST http://localhost:3010/webhook/orders \
+  -H "Content-Type: application/json" \
+  -d '{"item": "Widget", "quantity": 5}'
+
+# With authentication
+curl -X POST http://localhost:3010/webhook/secure \
+  -H "Authorization: Bearer your-token" \
+  -d '{"data": "value"}'
+```
+
+### Using HTTPie
+
+```bash
+http POST localhost:3010/webhook/test item=Widget quantity:=5
+```
+
+### External Testing
+
+Use services like:
+- [webhook.site](https://webhook.site) - Test outgoing webhooks
+- [ngrok](https://ngrok.com) - Expose local webhooks publicly
+
+---
+
+## Tips
+
+<Tip>
+Use **meaningful paths** that describe the purpose: `/webhook/orders`, `/webhook/stripe-events`
+</Tip>
+
+<Tip>
+Always **validate incoming data** before processing with Python Executor or similar.
+</Tip>
+
+<Tip>
+Return **appropriate status codes**: 200 (success), 400 (bad request), 500 (server error)
+</Tip>
+
+<Warning>
+In production, always enable authentication on webhooks that modify data.
+</Warning>
+
+---
+
+## Troubleshooting
+
+<Accordion title="Webhook not receiving requests">
+  - Verify workflow is **deployed** (not just saved)
+  - Check the path is correct (no leading slash)
+  - Ensure backend is running on correct port
+  - Check firewall/network settings
+</Accordion>
+
+<Accordion title="HTTP Request fails">
+  - Verify URL is correct and accessible
+  - Check headers (especially Content-Type)
+  - Look for CORS issues if calling from browser
+  - Check timeout setting for slow APIs
+</Accordion>
+
+<Accordion title="Response not sent">
+  - Ensure Webhook Response is connected to workflow
+  - Verify template variables resolve correctly
+  - Check status code is valid (100-599)
+</Accordion>
+
+---
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/quickstart">
+    Build a webhook workflow
+  </Card>
+  <Card title="Python Executor" icon="code" href="/nodes/schedulers">
+    Process webhook data
+  </Card>
+</CardGroup>