@xano/developer-mcp 1.0.21 → 1.0.22

package/dist/xanoscript_docs_auto/tasks.md

@@ -0,0 +1,479 @@
+---
+applyTo: "tasks/*.xs"
+---
+
+# Tasks
+
+Scheduled and cron jobs for automated operations.
+
+## Quick Reference
+
+```xs
+task "<name>" {
+  stack {
+    // Task logic
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 00:00:00+0000, freq: 86400}
+    ]
+  }
+}
+```
+
+---
+
+## Task Definition
+
+### Basic Task
+
+```xs
+task "daily_cleanup" {
+  stack {
+    // Delete old sessions
+    db.bulk.delete session {
+      where = $db.session.expires_at < now
+    }
+
+    debug.log { value = "Cleanup completed" }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 02:00:00+0000, freq: 86400}
+    ]
+  }
+}
+```
+
+### Task with Logic
+
+```xs
+task "send_reminders" {
+  stack {
+    // Find users with pending items
+    db.query user {
+      where = $db.user.has_pending == true
+            && $db.user.reminder_sent_at < now|transform_timestamp:"-1 day"
+    } as $users
+
+    foreach ($users) {
+      each as $user {
+        // Send reminder email
+        util.send_email {
+          to = $user.email
+          subject = "You have pending items"
+          body = "Please review your pending items."
+        }
+
+        // Update reminder timestamp
+        db.patch user {
+          field_name = "id"
+          field_value = $user.id
+          data = {reminder_sent_at: now}
+        }
+      }
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 09:00:00+0000, freq: 86400}
+    ]
+  }
+}
+```
+
+---
+
+## Schedule Configuration
+
+### Frequency Values (in seconds)
+
+| Interval | Seconds | Example |
+|----------|---------|---------|
+| Every minute | 60 | `freq: 60` |
+| Every 5 minutes | 300 | `freq: 300` |
+| Every 15 minutes | 900 | `freq: 900` |
+| Every hour | 3600 | `freq: 3600` |
+| Every 6 hours | 21600 | `freq: 21600` |
+| Every 12 hours | 43200 | `freq: 43200` |
+| Daily | 86400 | `freq: 86400` |
+| Weekly | 604800 | `freq: 604800` |
+
+### Schedule Examples
+
+```xs
+// Run every minute
+schedule {
+  events = [
+    {starts_on: 2025-01-01 00:00:00+0000, freq: 60}
+  ]
+}
+
+// Run every hour
+schedule {
+  events = [
+    {starts_on: 2025-01-01 00:00:00+0000, freq: 3600}
+  ]
+}
+
+// Run daily at 3 AM UTC
+schedule {
+  events = [
+    {starts_on: 2025-01-01 03:00:00+0000, freq: 86400}
+  ]
+}
+
+// Run weekly on Mondays at 9 AM
+schedule {
+  events = [
+    {starts_on: 2025-01-06 09:00:00+0000, freq: 604800}
+  ]
+}
+```
+
+### Multiple Schedules
+
+Run at different times:
+
+```xs
+schedule {
+  events = [
+    {starts_on: 2025-01-01 09:00:00+0000, freq: 86400},  // 9 AM daily
+    {starts_on: 2025-01-01 17:00:00+0000, freq: 86400}   // 5 PM daily
+  ]
+}
+```
+
+### End Date
+
+Schedule with an end date:
+
+```xs
+schedule {
+  events = [
+    {
+      starts_on: 2025-01-01 00:00:00+0000,
+      ends_on: 2025-12-31 23:59:59+0000,
+      freq: 86400
+    }
+  ]
+}
+```
+
+---
+
+## Common Task Patterns
+
+### Data Cleanup
+
+```xs
+task "cleanup_old_data" {
+  stack {
+    // Delete old logs
+    db.bulk.delete log {
+      where = $db.log.created_at < now|transform_timestamp:"-90 days"
+    }
+
+    // Delete expired tokens
+    db.bulk.delete token {
+      where = $db.token.expires_at < now
+    }
+
+    // Archive old orders
+    db.query order {
+      where = $db.order.status == "completed"
+            && $db.order.created_at < now|transform_timestamp:"-1 year"
+    } as $old_orders
+
+    foreach ($old_orders) {
+      each as $order {
+        // Move to archive table
+        db.add order_archive {
+          data = $order
+        }
+
+        // Delete from main table
+        db.del order {
+          field_name = "id"
+          field_value = $order.id
+        }
+      }
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 02:00:00+0000, freq: 86400}
+    ]
+  }
+}
+```
+
+### Report Generation
+
+```xs
+task "daily_sales_report" {
+  stack {
+    var $yesterday {
+      value = now|transform_timestamp:"-1 day"|format_timestamp:"Y-m-d":"UTC"
+    }
+
+    // Get sales data
+    db.query order {
+      where = $db.order.created_at|format_timestamp:"Y-m-d":"UTC" == $yesterday
+            && $db.order.status == "completed"
+    } as $orders
+
+    // Calculate totals
+    var $total_revenue {
+      value = $orders|map:$$.total|sum
+    }
+
+    var $order_count {
+      value = $orders|count
+    }
+
+    // Save report
+    db.add daily_report {
+      data = {
+        date: $yesterday,
+        order_count: $order_count,
+        total_revenue: $total_revenue,
+        created_at: now
+      }
+    }
+
+    // Send email
+    util.send_email {
+      to = $env.ADMIN_EMAIL
+      subject = "Daily Sales Report - " ~ $yesterday
+      body = "Orders: " ~ $order_count ~ "\nRevenue: $" ~ $total_revenue
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 06:00:00+0000, freq: 86400}
+    ]
+  }
+}
+```
+
+### External API Sync
+
+```xs
+task "sync_inventory" {
+  stack {
+    // Fetch from external API
+    api.request {
+      url = $env.INVENTORY_API_URL
+      method = "GET"
+      headers = {
+        "Authorization": "Bearer " ~ $env.INVENTORY_API_KEY
+      }
+    } as $external_data
+
+    // Update local products
+    foreach ($external_data.products) {
+      each as $product {
+        db.add_or_edit product {
+          field_name = "sku"
+          field_value = $product.sku
+          data = {
+            sku: $product.sku,
+            stock: $product.quantity,
+            price: $product.price,
+            synced_at: now
+          }
+        }
+      }
+    }
+
+    debug.log {
+      value = "Synced " ~ ($external_data.products|count) ~ " products"
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 00:00:00+0000, freq: 3600}  // Hourly
+    ]
+  }
+}
+```
+
+### Send Notifications
+
+```xs
+task "send_scheduled_notifications" {
+  stack {
+    // Find pending notifications
+    db.query notification {
+      where = $db.notification.send_at <= now
+            && $db.notification.sent == false
+      return = {type: "list", paging: {per_page: 100}}
+    } as $notifications
+
+    foreach ($notifications) {
+      each as $notification {
+        try_catch {
+          try {
+            util.send_email {
+              to = $notification.email
+              subject = $notification.subject
+              body = $notification.body
+            }
+
+            // Mark as sent
+            db.patch notification {
+              field_name = "id"
+              field_value = $notification.id
+              data = {sent: true, sent_at: now}
+            }
+          }
+          catch {
+            // Mark failed
+            db.patch notification {
+              field_name = "id"
+              field_value = $notification.id
+              data = {
+                error: $error.message,
+                retry_count: $notification.retry_count + 1
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 00:00:00+0000, freq: 60}  // Every minute
+    ]
+  }
+}
+```
+
+### Subscription Billing
+
+```xs
+task "process_subscriptions" {
+  stack {
+    // Find subscriptions due for billing
+    db.query subscription {
+      where = $db.subscription.next_billing_date <= now
+            && $db.subscription.status == "active"
+    } as $subscriptions
+
+    foreach ($subscriptions) {
+      each as $sub {
+        try_catch {
+          try {
+            // Process payment
+            function.run "charge_subscription" {
+              input = {subscription_id: $sub.id}
+            } as $payment
+
+            // Update next billing date
+            db.patch subscription {
+              field_name = "id"
+              field_value = $sub.id
+              data = {
+                next_billing_date: $sub.next_billing_date|transform_timestamp:"+1 month",
+                last_billed_at: now
+              }
+            }
+          }
+          catch {
+            // Handle failed payment
+            db.patch subscription {
+              field_name = "id"
+              field_value = $sub.id
+              data = {
+                status: "past_due",
+                billing_error: $error.message
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 00:00:00+0000, freq: 3600}
+    ]
+  }
+}
+```
+
+---
+
+## Error Handling in Tasks
+
+```xs
+task "critical_task" {
+  stack {
+    try_catch {
+      try {
+        // Main task logic
+        function.run "important_operation" {} as $result
+      }
+      catch {
+        // Log error
+        db.add task_error {
+          data = {
+            task: "critical_task",
+            error: $error.message,
+            created_at: now
+          }
+        }
+
+        // Alert admin
+        util.send_email {
+          to = $env.ADMIN_EMAIL
+          subject = "Task Failed: critical_task"
+          body = "Error: " ~ $error.message
+        }
+      }
+    }
+  }
+  schedule {
+    events = [
+      {starts_on: 2025-01-01 00:00:00+0000, freq: 3600}
+    ]
+  }
+}
+```
+
+---
+
+## Testing Tasks
+
+```xs
+task "process_data" {
+  stack {
+    db.query data {} as $data
+    // Processing logic
+  }
+
+  test "processes empty data" {
+    task.call {
+      mock = {
+        "db.query data": []
+      }
+    } as $result
+
+    expect.to_be_true { input = true }
+  }
+
+  test "processes sample data" {
+    task.call {
+      mock = {
+        "db.query data": [{id: 1, value: 100}]
+      }
+    } as $result
+
+    expect.to_equal { input = $result.processed, value = 1 }
+  }
+
+  schedule { ... }
+}
+```