@xano/developer-mcp 1.0.1 → 1.0.2

package/xanoscript_docs/tables.md

@@ -0,0 +1,270 @@
+---
+applyTo: "tables/*.xs"
+---
+
+# Tables
+
+Database table definitions in XanoScript.
+
+## Quick Reference
+
+```xs
+table "<name>" {
+  auth = false                    # true if used for authentication
+  schema {
+    int id                        # Primary key (required)
+    text name filters=trim
+    timestamp created_at?=now
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+}
+```
+
+### Field Types
+`int`, `text`, `email`, `password`, `decimal`, `bool`, `timestamp`, `date`, `uuid`, `vector`, `json`, `image`, `video`, `audio`, `attachment`, `enum`
+
+### Index Types
+`primary`, `btree`, `btree|unique`, `gin`
+
+---
+
+## Basic Structure
+
+Every table requires an `id` field as the primary key:
+
+```xs
+table "user" {
+  auth = true
+  schema {
+    int id
+    text name filters=trim
+    email email filters=trim|lower {
+      sensitive = true
+    }
+    password password
+    timestamp created_at?=now
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+    {type: "btree|unique", field: [{name: "email"}]}
+  ]
+}
+```
+
+---
+
+## Schema Fields
+
+### Basic Fields
+```xs
+schema {
+  int id
+  text name
+  decimal price
+  bool is_active
+  timestamp created_at
+  date birth_date
+}
+```
+
+### Optional & Defaults
+```xs
+schema {
+  text nickname?                   # Optional, no default
+  timestamp created_at?=now        # Optional, defaults to current time
+  bool is_active?=true             # Optional, defaults to true
+  int status?=0                    # Optional, defaults to 0
+}
+```
+
+### With Filters
+```xs
+schema {
+  text name filters=trim
+  email email filters=trim|lower
+  int quantity filters=min:0
+  text category filters=trim|lower
+}
+```
+
+### With Metadata
+```xs
+schema {
+  text ssn {
+    description = "Social Security Number"
+    sensitive = true
+  }
+  email email filters=lower {
+    description = "Primary contact email"
+    sensitive = true
+  }
+}
+```
+
+### Foreign Keys
+```xs
+schema {
+  int user_id {
+    table = "user"
+    description = "Reference to user table"
+  }
+  uuid order_id {
+    table = "order"
+  }
+}
+```
+
+### Enum Fields
+```xs
+schema {
+  enum status {
+    values = ["pending", "active", "completed", "cancelled"]
+  }
+  enum priority?="medium" {
+    values = ["low", "medium", "high"]
+  }
+}
+```
+
+### JSON Fields
+```xs
+schema {
+  json metadata
+  json settings?={}
+}
+```
+
+### Vector Fields
+```xs
+schema {
+  vector embedding              # For AI/ML embeddings
+}
+```
+
+---
+
+## Indexes
+
+### Primary Key
+```xs
+index = [
+  {type: "primary", field: [{name: "id"}]}
+]
+```
+
+### B-tree Index
+```xs
+index = [
+  {type: "btree", field: [{name: "email", op: "asc"}]}
+  {type: "btree", field: [{name: "created_at", op: "desc"}]}
+]
+```
+
+### Unique Index
+```xs
+index = [
+  {type: "btree|unique", field: [{name: "email"}]}
+  {type: "btree|unique", field: [{name: "username"}]}
+]
+```
+
+### Composite Index
+```xs
+index = [
+  {type: "btree", field: [{name: "user_id"}, {name: "created_at", op: "desc"}]}
+]
+```
+
+### GIN Index (for JSON/arrays)
+```xs
+index = [
+  {type: "gin", field: [{name: "tags", op: "jsonb_path_op"}]}
+  {type: "gin", field: [{name: "metadata", op: "jsonb_path_op"}]}
+]
+```
+
+---
+
+## Complete Examples
+
+### User Table (with auth)
+```xs
+table "user" {
+  auth = true
+  schema {
+    int id
+    text name filters=trim
+    email email filters=trim|lower { sensitive = true }
+    password password { sensitive = true }
+    enum role?="user" { values = ["user", "admin", "moderator"] }
+    bool is_active?=true
+    timestamp created_at?=now
+    timestamp updated_at?
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+    {type: "btree|unique", field: [{name: "email"}]}
+    {type: "btree", field: [{name: "role"}]}
+  ]
+}
+```
+
+### Product Table
+```xs
+table "product" {
+  auth = false
+  schema {
+    int id
+    text name filters=trim
+    text description?
+    decimal price filters=min:0
+    int stock_quantity?=0 filters=min:0
+    int category_id { table = "category" }
+    json metadata?
+    bool is_published?=false
+    timestamp created_at?=now
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+    {type: "btree", field: [{name: "category_id"}]}
+    {type: "btree", field: [{name: "is_published"}]}
+  ]
+}
+```
+
+### Order with Foreign Keys
+```xs
+table "order" {
+  auth = false
+  schema {
+    int id
+    int user_id { table = "user" }
+    decimal total filters=min:0
+    enum status?="pending" { values = ["pending", "processing", "shipped", "delivered", "cancelled"] }
+    json shipping_address
+    timestamp created_at?=now
+    timestamp updated_at?
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+    {type: "btree", field: [{name: "user_id"}]}
+    {type: "btree", field: [{name: "status"}]}
+    {type: "btree", field: [{name: "created_at", op: "desc"}]}
+  ]
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always define `id`** - Every table needs a primary key named `id`
+2. **Use `auth = true`** only for authentication tables (typically just `user`)
+3. **Add indexes** for fields used in WHERE clauses and JOINs
+4. **Use appropriate types** - `email` for emails, `password` for credentials
+5. **Mark sensitive fields** - Set `sensitive = true` for PII
+6. **Use filters** - Apply `trim`, `lower` for consistency
+7. **Default timestamps** - Use `?=now` for created_at fields
+8. **Document with descriptions** - Add descriptions for non-obvious fields

package/xanoscript_docs/tasks.md

@@ -0,0 +1,254 @@
+---
+applyTo: "tasks/*.xs"
+---
+
+# Tasks
+
+Scheduled jobs in XanoScript.
+
+## Quick Reference
+
+```xs
+task "<name>" {
+  description = "What this task does"
+  stack { ... }
+  schedule = [{starts_on: YYYY-MM-DD HH:MM:SS+0000, freq: <seconds>}]
+}
+```
+
+### Common Frequencies
+| Interval | Seconds |
+|----------|---------|
+| 1 minute | 60 |
+| 5 minutes | 300 |
+| 1 hour | 3600 |
+| Daily | 86400 |
+| Weekly | 604800 |
+
+---
+
+## Basic Structure
+
+```xs
+task "daily_cleanup" {
+  description = "Clean up expired sessions daily at midnight UTC"
+  stack {
+    db.query "session" {
+      where = $db.session.expires_at < now
+    } as $expired
+
+    foreach ($expired) {
+      each as $session {
+        db.del "session" {
+          field_name = "id"
+          field_value = $session.id
+        }
+      }
+    }
+
+    debug.log { value = "Cleaned " ~ ($expired|count) ~ " sessions" }
+  }
+  schedule = [{starts_on: 2025-01-01 00:00:00+0000, freq: 86400}]
+}
+```
+
+---
+
+## Schedule Configuration
+
+### Single Event
+```xs
+schedule = [{starts_on: 2025-06-15 09:00:00+0000, freq: 86400}]
+```
+
+### With End Date
+```xs
+schedule = [{
+  starts_on: 2025-01-01 08:00:00+0000,
+  freq: 3600,
+  ends_on: 2025-12-31 23:59:59+0000
+}]
+```
+
+### Multiple Schedules
+```xs
+schedule = [
+  {starts_on: 2025-01-01 09:00:00+0000, freq: 86400},
+  {starts_on: 2025-01-01 21:00:00+0000, freq: 86400}
+]
+```
+
+---
+
+## Common Patterns
+
+### Data Aggregation
+```xs
+task "hourly_stats" {
+  description = "Aggregate hourly statistics"
+  stack {
+    var $hour_ago { value = now|transform_timestamp:"-1 hour" }
+
+    db.query "order" {
+      where = $db.order.created_at >= $hour_ago
+    } as $orders
+
+    db.add "hourly_stats" {
+      data = {
+        hour: $hour_ago,
+        order_count: $orders|count,
+        total_revenue: ($orders|map:$$.total)|sum
+      }
+    }
+  }
+  schedule = [{starts_on: 2025-01-01 00:00:00+0000, freq: 3600}]
+}
+```
+
+### Cleanup Job
+```xs
+task "cleanup_temp_files" {
+  description = "Delete temporary files older than 24 hours"
+  stack {
+    var $cutoff { value = now|transform_timestamp:"-24 hours" }
+
+    db.query "temp_file" {
+      where = $db.temp_file.created_at < $cutoff
+    } as $files
+
+    foreach ($files) {
+      each as $file {
+        storage.delete_file { pathname = $file.path }
+        db.del "temp_file" {
+          field_name = "id"
+          field_value = $file.id
+        }
+      }
+    }
+  }
+  schedule = [{starts_on: 2025-01-01 03:00:00+0000, freq: 86400}]
+}
+```
+
+### Notification Job
+```xs
+task "daily_digest" {
+  description = "Send daily digest emails"
+  stack {
+    db.query "user" {
+      where = $db.user.digest_enabled == true
+    } as $users
+
+    foreach ($users) {
+      each as $user {
+        db.query "notification" {
+          where = $db.notification.user_id == $user.id
+            && $db.notification.sent == false
+        } as $notifications
+
+        conditional {
+          if (($notifications|count) > 0) {
+            util.send_email {
+              service_provider = "resend"
+              api_key = $env.RESEND_API_KEY
+              to = $user.email
+              from = "noreply@example.com"
+              subject = "Your Daily Digest"
+              message = "You have " ~ ($notifications|count) ~ " new notifications"
+            }
+          }
+        }
+      }
+    }
+  }
+  schedule = [{starts_on: 2025-01-01 08:00:00+0000, freq: 86400}]
+}
+```
+
+### External API Sync
+```xs
+task "sync_exchange_rates" {
+  description = "Sync currency exchange rates every hour"
+  stack {
+    api.request {
+      url = "https://api.exchangerate.com/latest"
+      method = "GET"
+      headers = []|push:("Authorization: Bearer " ~ $env.EXCHANGE_API_KEY)
+    } as $response
+
+    foreach ($response.rates|entries) {
+      each as $rate {
+        db.add_or_edit "exchange_rate" {
+          field_name = "currency"
+          field_value = $rate.key
+          data = {
+            currency: $rate.key,
+            rate: $rate.value,
+            updated_at: now
+          }
+        }
+      }
+    }
+  }
+  schedule = [{starts_on: 2025-01-01 00:00:00+0000, freq: 3600}]
+}
+```
+
+---
+
+## Stack Operations
+
+Tasks use the same stack operations as functions:
+
+- `db.query`, `db.add`, `db.edit`, `db.del` - Database operations
+- `api.request` - External API calls
+- `function.run` - Call functions
+- `foreach`, `for`, `while` - Loops
+- `conditional` - Branching
+- `debug.log` - Logging
+- `util.send_email` - Send emails
+- `try_catch` - Error handling
+
+---
+
+## Error Handling
+
+```xs
+task "risky_sync" {
+  stack {
+    try_catch {
+      try {
+        api.request {
+          url = "https://external-api.com/data"
+          method = "GET"
+        } as $data
+        # Process data...
+      }
+      catch {
+        util.send_email {
+          service_provider = "resend"
+          api_key = $env.RESEND_API_KEY
+          to = "alerts@example.com"
+          from = "system@example.com"
+          subject = "Sync Task Failed"
+          message = "The risky_sync task failed"
+        }
+      }
+    }
+  }
+  schedule = [{starts_on: 2025-01-01 00:00:00+0000, freq: 3600}]
+}
+```
+
+---
+
+## Best Practices
+
+1. **Use descriptive names** - Indicate what and when: `daily_cleanup`, `hourly_sync`
+2. **Add descriptions** - Explain the purpose and schedule
+3. **Handle errors** - Use try_catch for external dependencies
+4. **Log important events** - Use debug.log for tracking
+5. **Use appropriate frequency** - Don't run more often than needed
+6. **Consider timezone** - Schedule uses UTC (+0000)
+7. **Batch operations** - Process in chunks for large datasets
+8. **Set end dates** - Use ends_on for temporary schedules