@xano/developer-mcp 1.0.25 → 1.0.27

package/dist/xanoscript_docs_auto/triggers.md

@@ -1,595 +0,0 @@
----
-applyTo: "triggers/**/*.xs"
----
-
-# Triggers
-
-Event-driven handlers for database, realtime, workspace, agent, and MCP events.
-
-## Quick Reference
-
-| Trigger Type | Purpose |
-|--------------|---------|
-| `table_trigger` | Database table events (insert, update, delete) |
-| `realtime_trigger` | Real-time channel events |
-| `workspace_trigger` | Workspace-level events |
-| `agent_trigger` | AI agent events |
-| `mcp_server_trigger` | MCP server events |
-
----
-
-## Table Triggers
-
-React to database table changes:
-
-### On Insert
-
-```xs
-table_trigger "user_created" {
-  table = user
-  event = insert
-
-  stack {
-    // Send welcome email
-    util.send_email {
-      to = $trigger.new.email
-      subject = "Welcome!"
-      body = "Thank you for signing up, " ~ $trigger.new.name ~ "!"
-    }
-
-    // Create initial preferences
-    db.add user_preference {
-      data = {
-        user_id: $trigger.new.id,
-        theme: "light",
-        notifications: true
-      }
-    }
-  }
-}
-```
-
-### On Update
-
-```xs
-table_trigger "order_status_changed" {
-  table = order
-  event = update
-
-  stack {
-    // Check if status changed
-    conditional {
-      if ($trigger.old.status != $trigger.new.status) {
-        // Log status change
-        db.add order_history {
-          data = {
-            order_id: $trigger.new.id,
-            old_status: $trigger.old.status,
-            new_status: $trigger.new.status,
-            changed_at: now
-          }
-        }
-
-        // Notify customer
-        conditional {
-          if ($trigger.new.status == "shipped") {
-            util.send_email {
-              to = $trigger.new.customer_email
-              subject = "Your order has shipped!"
-              body = "Order #" ~ $trigger.new.order_number ~ " is on its way."
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### On Delete
-
-```xs
-table_trigger "user_deleted" {
-  table = user
-  event = delete
-
-  stack {
-    // Clean up related data
-    db.bulk.delete session {
-      where = $db.session.user_id == $trigger.old.id
-    }
-
-    db.bulk.delete user_preference {
-      where = $db.user_preference.user_id == $trigger.old.id
-    }
-
-    // Log deletion
-    db.add audit_log {
-      data = {
-        action: "user_deleted",
-        user_id: $trigger.old.id,
-        user_email: $trigger.old.email,
-        deleted_at: now
-      }
-    }
-  }
-}
-```
-
----
-
-## Trigger Context
-
-### $trigger.new
-
-New record data (available on insert and update):
-
-```xs
-$trigger.new.id
-$trigger.new.name
-$trigger.new.email
-$trigger.new.created_at
-```
-
-### $trigger.old
-
-Previous record data (available on update and delete):
-
-```xs
-$trigger.old.id
-$trigger.old.status
-$trigger.old.updated_at
-```
-
-### Comparing Old and New
-
-```xs
-table_trigger "price_changed" {
-  table = product
-  event = update
-
-  stack {
-    conditional {
-      if ($trigger.old.price != $trigger.new.price) {
-        // Price changed - log it
-        db.add price_history {
-          data = {
-            product_id: $trigger.new.id,
-            old_price: $trigger.old.price,
-            new_price: $trigger.new.price,
-            changed_at: now
-          }
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Multiple Events
-
-Handle multiple events in one trigger:
-
-```xs
-table_trigger "product_audit" {
-  table = product
-  event = [insert, update, delete]
-
-  stack {
-    var $action {
-      value = $trigger.event  // "insert", "update", or "delete"
-    }
-
-    db.add audit_log {
-      data = {
-        table_name: "product",
-        action: $action,
-        record_id: ($trigger.new ?? $trigger.old).id,
-        old_data: $trigger.old|json_encode,
-        new_data: $trigger.new|json_encode,
-        created_at: now
-      }
-    }
-  }
-}
-```
-
----
-
-## Realtime Triggers
-
-Handle real-time channel events:
-
-```xs
-realtime_trigger "chat_message" {
-  channel = "chat:*"
-  event = message
-
-  stack {
-    // Store message
-    db.add chat_message {
-      data = {
-        channel: $trigger.channel,
-        user_id: $trigger.user_id,
-        message: $trigger.data.message,
-        created_at: now
-      }
-    }
-
-    // Broadcast to other users
-    api.realtime_event {
-      channel = $trigger.channel
-      event = "new_message"
-      data = {
-        user_id: $trigger.user_id,
-        message: $trigger.data.message,
-        timestamp: now
-      }
-    }
-  }
-}
-```
-
-### Channel Patterns
-
-```xs
-// Exact channel match
-channel = "notifications"
-
-// Wildcard pattern
-channel = "chat:*"           // Matches chat:room1, chat:room2, etc.
-channel = "user:*:updates"   // Matches user:123:updates
-```
-
----
-
-## Workspace Triggers
-
-Handle workspace-level events:
-
-```xs
-workspace_trigger "on_error" {
-  event = error
-
-  stack {
-    // Log errors
-    db.add error_log {
-      data = {
-        error_type: $trigger.error.type,
-        error_message: $trigger.error.message,
-        stack_trace: $trigger.error.stack,
-        request_path: $trigger.request.path,
-        user_id: $trigger.auth.id,
-        created_at: now
-      }
-    }
-
-    // Alert on critical errors
-    conditional {
-      if ($trigger.error.code >= 500) {
-        util.send_email {
-          to = $env.ADMIN_EMAIL
-          subject = "Critical Error Alert"
-          body = $trigger.error.message
-        }
-      }
-    }
-  }
-}
-```
-
-### Workspace Events
-
-| Event | Description |
-|-------|-------------|
-| `error` | Runtime error occurred |
-| `request` | API request received |
-| `response` | API response sent |
-
----
-
-## Agent Triggers
-
-Handle AI agent events:
-
-```xs
-agent_trigger "on_completion" {
-  agent = "customer_support"
-  event = completion
-
-  stack {
-    // Log agent response
-    db.add agent_log {
-      data = {
-        agent: $trigger.agent,
-        conversation_id: $trigger.conversation_id,
-        input: $trigger.input,
-        output: $trigger.output,
-        tokens_used: $trigger.usage.total_tokens,
-        created_at: now
-      }
-    }
-  }
-}
-```
-
-### Agent Events
-
-| Event | Description |
-|-------|-------------|
-| `completion` | Agent completed response |
-| `tool_call` | Agent called a tool |
-| `error` | Agent encountered error |
-
-### Tool Call Trigger
-
-```xs
-agent_trigger "log_tool_usage" {
-  agent = "*"  // All agents
-  event = tool_call
-
-  stack {
-    db.add tool_usage {
-      data = {
-        agent: $trigger.agent,
-        tool_name: $trigger.tool.name,
-        tool_input: $trigger.tool.input|json_encode,
-        tool_output: $trigger.tool.output|json_encode,
-        created_at: now
-      }
-    }
-  }
-}
-```
-
----
-
-## MCP Server Triggers
-
-Handle MCP (Model Context Protocol) server events:
-
-```xs
-mcp_server_trigger "tool_invoked" {
-  server = "my_mcp_server"
-  event = tool_call
-
-  stack {
-    db.add mcp_log {
-      data = {
-        server: $trigger.server,
-        tool: $trigger.tool,
-        input: $trigger.input|json_encode,
-        created_at: now
-      }
-    }
-  }
-}
-```
-
----
-
-## Common Patterns
-
-### Audit Trail
-
-```xs
-table_trigger "audit_all_changes" {
-  table = [user, product, order]
-  event = [insert, update, delete]
-
-  stack {
-    db.add audit_trail {
-      data = {
-        table_name: $trigger.table,
-        record_id: ($trigger.new ?? $trigger.old).id,
-        action: $trigger.event,
-        user_id: $auth.id,
-        old_data: $trigger.old,
-        new_data: $trigger.new,
-        ip_address: $env.$remote_ip,
-        created_at: now
-      }
-    }
-  }
-}
-```
-
-### Cache Invalidation
-
-```xs
-table_trigger "invalidate_cache" {
-  table = product
-  event = [update, delete]
-
-  stack {
-    // Clear product cache
-    redis.del {
-      key = "product:" ~ ($trigger.new ?? $trigger.old).id
-    }
-
-    // Clear category cache
-    redis.del {
-      key = "category:" ~ ($trigger.new ?? $trigger.old).category_id
-    }
-
-    // Clear listing cache
-    redis.del {
-      key = "products:list"
-    }
-  }
-}
-```
-
-### Cascading Updates
-
-```xs
-table_trigger "update_order_totals" {
-  table = order_item
-  event = [insert, update, delete]
-
-  stack {
-    var $order_id {
-      value = ($trigger.new ?? $trigger.old).order_id
-    }
-
-    // Recalculate order total
-    db.query order_item {
-      where = $db.order_item.order_id == $order_id
-    } as $items
-
-    var $new_total {
-      value = $items|map:$$.total|sum
-    }
-
-    db.patch order {
-      field_name = "id"
-      field_value = $order_id
-      data = {
-        total: $new_total,
-        updated_at: now
-      }
-    }
-  }
-}
-```
-
-### Notifications
-
-```xs
-table_trigger "notify_on_mention" {
-  table = comment
-  event = insert
-
-  stack {
-    // Extract mentioned users
-    var $mentions {
-      value = $trigger.new.content|regex_get_all_matches:"@(\w+)"
-    }
-
-    foreach ($mentions) {
-      each as $username {
-        db.get user {
-          field_name = "username"
-          field_value = $username
-        } as $user
-
-        conditional {
-          if ($user != null) {
-            db.add notification {
-              data = {
-                user_id: $user.id,
-                type: "mention",
-                message: "You were mentioned in a comment",
-                reference_id: $trigger.new.id,
-                created_at: now
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Error Handling
-
-```xs
-table_trigger "safe_trigger" {
-  table = order
-  event = insert
-
-  stack {
-    try_catch {
-      try {
-        // Send notification
-        util.send_email {
-          to = $trigger.new.customer_email
-          subject = "Order Confirmation"
-          body = "Your order has been received."
-        }
-      }
-      catch {
-        // Log error but don't fail the trigger
-        db.add trigger_error {
-          data = {
-            trigger: "safe_trigger",
-            error: $error.message,
-            record_id: $trigger.new.id,
-            created_at: now
-          }
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Best Practices
-
-### Keep Triggers Fast
-
-Triggers run synchronously. For heavy processing:
-
-```xs
-table_trigger "queue_processing" {
-  table = order
-  event = insert
-
-  stack {
-    // Add to queue instead of processing inline
-    redis.push {
-      key = "queue:order_processing"
-      value = $trigger.new.id|to_text
-    }
-  }
-}
-```
-
-### Avoid Infinite Loops
-
-Be careful with triggers that update the same table:
-
-```xs
-table_trigger "safe_update" {
-  table = order
-  event = update
-
-  stack {
-    // Only act on specific field changes
-    conditional {
-      if ($trigger.old.status != $trigger.new.status) {
-        // This is safe - we're checking the specific change
-        // Don't update status here or you'll create a loop
-      }
-    }
-  }
-}
-```
-
-### Use Conditions
-
-Filter when triggers fire:
-
-```xs
-table_trigger "notify_high_value" {
-  table = order
-  event = insert
-  condition = $trigger.new.total > 1000
-
-  stack {
-    // Only runs for orders over $1000
-    util.send_email {
-      to = $env.SALES_EMAIL
-      subject = "High-value order received!"
-      body = "Order #" ~ $trigger.new.order_number ~ " for $" ~ $trigger.new.total
-    }
-  }
-}
-```