@xano/developer-mcp 1.0.7 → 1.0.9

package/xanoscript_docs/realtime.md

@@ -0,0 +1,382 @@
+---
+applyTo: "functions/**/*.xs, apis/**/*.xs, triggers/**/*.xs"
+---
+
+# Realtime
+
+Push real-time updates to connected clients using channels and events.
+
+## Quick Reference
+
+| Operation | Purpose |
+|-----------|---------|
+| `api.realtime_event` | Send event to channel |
+| Channel patterns | Organize subscriptions |
+| Realtime triggers | Handle client events |
+
+---
+
+## api.realtime_event
+
+Send a real-time event to subscribed clients.
+
+```xs
+api.realtime_event {
+  channel = "orders"
+  event = "new_order"
+  data = {
+    order_id: $order.id,
+    total: $order.total,
+    customer: $order.customer_name
+  }
+}
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `channel` | text | Channel name or pattern |
+| `event` | text | Event type name |
+| `data` | any | Payload to send |
+
+---
+
+## Channel Patterns
+
+### Public Channels
+
+Available to all authenticated clients.
+
+```xs
+// Global announcements
+api.realtime_event {
+  channel = "announcements"
+  event = "system_update"
+  data = { message: "Maintenance in 10 minutes" }
+}
+```
+
+### User-Specific Channels
+
+Target individual users.
+
+```xs
+// Notify specific user
+api.realtime_event {
+  channel = "user:" ~ $user.id
+  event = "notification"
+  data = {
+    title: "New message",
+    body: "You have a new message from " ~ $sender.name
+  }
+}
+```
+
+### Resource Channels
+
+Updates for specific resources.
+
+```xs
+// Update watchers of a document
+api.realtime_event {
+  channel = "document:" ~ $document.id
+  event = "content_updated"
+  data = {
+    updated_by: $auth.id,
+    updated_at: now,
+    changes: $changes
+  }
+}
+```
+
+### Tenant Channels
+
+Multi-tenant isolation.
+
+```xs
+api.realtime_event {
+  channel = "tenant:" ~ $env.$tenant ~ ":orders"
+  event = "order_created"
+  data = $order
+}
+```
+
+---
+
+## Broadcast Patterns
+
+### To All Connected Users
+
+```xs
+api.realtime_event {
+  channel = "global"
+  event = "broadcast"
+  data = { message: $input.message }
+}
+```
+
+### To Role-Based Groups
+
+```xs
+// Notify all admins
+foreach ($admin_users) {
+  each as $admin {
+    api.realtime_event {
+      channel = "user:" ~ $admin.id
+      event = "admin_alert"
+      data = $alert_data
+    }
+  }
+}
+```
+
+### To Room/Group
+
+```xs
+api.realtime_event {
+  channel = "room:" ~ $input.room_id
+  event = "message"
+  data = {
+    sender_id: $auth.id,
+    content: $input.message,
+    sent_at: now
+  }
+}
+```
+
+---
+
+## Realtime Triggers
+
+Handle events from connected clients.
+
+### Basic Realtime Trigger
+
+```xs
+realtime_trigger "on_presence" {
+  channel = "room:*"
+  event = "join"
+  stack {
+    // $input contains event data
+    // $channel contains matched channel
+    db.add "presence" {
+      data = {
+        user_id: $auth.id,
+        room_id: $input.room_id,
+        joined_at: now
+      }
+    }
+
+    // Notify room members
+    api.realtime_event {
+      channel = $channel
+      event = "user_joined"
+      data = { user_id: $auth.id }
+    }
+  }
+}
+```
+
+### Channel Pattern Matching
+
+```xs
+realtime_trigger "document_cursor" {
+  channel = "document:*"               // Wildcard match
+  event = "cursor_move"
+  stack {
+    // Broadcast cursor position to other viewers
+    api.realtime_event {
+      channel = $channel
+      event = "cursor_update"
+      data = {
+        user_id: $auth.id,
+        position: $input.position
+      }
+    }
+  }
+}
+```
+
+---
+
+## Common Patterns
+
+### Chat Application
+
+```xs
+function "send_chat_message" {
+  input {
+    int room_id
+    text content filters=trim|max:1000
+  }
+  stack {
+    // Save message
+    db.add "message" {
+      data = {
+        room_id: $input.room_id,
+        sender_id: $auth.id,
+        content: $input.content,
+        created_at: now
+      }
+    } as $message
+
+    // Broadcast to room
+    api.realtime_event {
+      channel = "room:" ~ $input.room_id
+      event = "new_message"
+      data = {
+        id: $message.id,
+        sender_id: $auth.id,
+        content: $input.content,
+        created_at: $message.created_at
+      }
+    }
+  }
+  response = $message
+}
+```
+
+### Live Dashboard Updates
+
+```xs
+function "update_metrics" {
+  stack {
+    // Calculate metrics
+    db.query "order" {
+      where = $db.order.created_at >= now|transform_timestamp:"-1 hour"
+    } as $recent_orders
+
+    var $metrics {
+      value = {
+        orders_last_hour: $recent_orders|count,
+        revenue_last_hour: $recent_orders|map:$$.total|sum,
+        updated_at: now
+      }
+    }
+
+    // Push to dashboard subscribers
+    api.realtime_event {
+      channel = "dashboard:metrics"
+      event = "update"
+      data = $metrics
+    }
+  }
+  response = $metrics
+}
+```
+
+### Collaborative Editing
+
+```xs
+realtime_trigger "document_edit" {
+  channel = "document:*"
+  event = "operation"
+  stack {
+    // Apply operation to document
+    function.run "apply_document_op" {
+      input = {
+        document_id: $input.document_id,
+        operation: $input.operation,
+        user_id: $auth.id
+      }
+    } as $result
+
+    // Broadcast to other editors
+    api.realtime_event {
+      channel = $channel
+      event = "remote_operation"
+      data = {
+        operation: $input.operation,
+        user_id: $auth.id,
+        version: $result.version
+      }
+    }
+  }
+}
+```
+
+### Notification System
+
+```xs
+function "notify_user" {
+  input {
+    int user_id
+    text type
+    text title
+    text body
+    json? data
+  }
+  stack {
+    // Save notification
+    db.add "notification" {
+      data = {
+        user_id: $input.user_id,
+        type: $input.type,
+        title: $input.title,
+        body: $input.body,
+        data: $input.data,
+        read: false,
+        created_at: now
+      }
+    } as $notification
+
+    // Push to user
+    api.realtime_event {
+      channel = "user:" ~ $input.user_id
+      event = "notification"
+      data = $notification
+    }
+  }
+  response = $notification
+}
+```
+
+---
+
+## Subscription Management
+
+Clients subscribe to channels client-side. Server controls what events to send.
+
+### Authorization Pattern
+
+```xs
+// Validate user can access channel before sending
+function "send_to_room" {
+  input {
+    int room_id
+    text event
+    json data
+  }
+  stack {
+    // Check membership
+    db.query "room_member" {
+      where = $db.room_member.room_id == $input.room_id
+            && $db.room_member.user_id == $auth.id
+      return = { type: "exists" }
+    } as $is_member
+
+    precondition ($is_member) {
+      error_type = "accessdenied"
+      error = "Not a member of this room"
+    }
+
+    api.realtime_event {
+      channel = "room:" ~ $input.room_id
+      event = $input.event
+      data = $input.data
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Use channel namespacing** - `type:id` format for clarity
+2. **Keep payloads small** - Send IDs, let client fetch details
+3. **Validate before broadcast** - Don't trust client event data
+4. **Use triggers for client events** - Handle incoming realtime events
+5. **Consider fan-out carefully** - Large broadcasts can be expensive
+6. **Implement presence** - Track who's connected to channels

package/xanoscript_docs/schema.md

@@ -0,0 +1,292 @@
+---
+applyTo: "functions/**/*.xs, apis/**/*.xs"
+---
+
+# Schema Operations
+
+Runtime schema parsing and validation for dynamic data structures.
+
+## Quick Reference
+
+| Function | Purpose |
+|----------|---------|
+| `schema.parse` | Parse and validate any schema |
+| `schema.parse.object` | Parse object schema |
+| `schema.parse.array` | Parse array schema |
+| `schema.parse.attribute` | Parse single attribute |
+| `schema.parse.constant` | Parse constant value |
+| `schema.parse.enum` | Parse enum value |
+| `schema.parse.immutable` | Parse immutable structure |
+
+---
+
+## schema.parse
+
+Parse and validate data against a dynamic schema.
+
+```xs
+schema.parse {
+  data = $input.payload
+  schema = {
+    type: "object",
+    properties: {
+      name: { type: "text", required: true },
+      email: { type: "email", filters: ["trim", "lower"] },
+      age: { type: "int", filters: ["min:0", "max:150"] }
+    }
+  }
+} as $validated
+```
+
+### Schema Definition
+
+| Property | Description |
+|----------|-------------|
+| `type` | Data type (text, int, decimal, bool, object, array, etc.) |
+| `required` | Whether field is required (default: false) |
+| `nullable` | Whether null is allowed (default: false) |
+| `default` | Default value if not provided |
+| `filters` | Array of validation filters |
+| `properties` | Nested properties (for object type) |
+| `items` | Item schema (for array type) |
+
+---
+
+## schema.parse.object
+
+Parse and validate an object structure.
+
+```xs
+schema.parse.object {
+  data = $input.user
+  schema = {
+    id: { type: "int", required: true },
+    profile: {
+      type: "object",
+      properties: {
+        name: { type: "text", required: true },
+        bio: { type: "text", nullable: true, filters: ["max:500"] }
+      }
+    },
+    roles: { type: "array", items: { type: "text" } }
+  }
+} as $user
+```
+
+### With Defaults
+
+```xs
+schema.parse.object {
+  data = $input.settings
+  schema = {
+    theme: { type: "text", default: "light" },
+    notifications: { type: "bool", default: true },
+    language: { type: "text", default: "en" }
+  }
+} as $settings
+```
+
+---
+
+## schema.parse.array
+
+Parse and validate an array structure.
+
+```xs
+schema.parse.array {
+  data = $input.items
+  schema = {
+    min_items: 1,
+    max_items: 100,
+    items: {
+      type: "object",
+      properties: {
+        product_id: { type: "int", required: true },
+        quantity: { type: "int", required: true, filters: ["min:1"] }
+      }
+    }
+  }
+} as $items
+```
+
+### Flat Array
+
+```xs
+schema.parse.array {
+  data = $input.tags
+  schema = {
+    items: { type: "text", filters: ["trim", "lower"] },
+    unique: true
+  }
+} as $tags
+```
+
+---
+
+## schema.parse.attribute
+
+Parse a single attribute value.
+
+```xs
+schema.parse.attribute {
+  data = $input.email
+  schema = {
+    type: "email",
+    required: true,
+    filters: ["trim", "lower"]
+  }
+} as $email
+```
+
+### With Custom Validation
+
+```xs
+schema.parse.attribute {
+  data = $input.phone
+  schema = {
+    type: "text",
+    pattern: "^\\+?[1-9]\\d{1,14}$",
+    error_message: "Invalid phone number format"
+  }
+} as $phone
+```
+
+---
+
+## schema.parse.constant
+
+Validate that a value matches an expected constant.
+
+```xs
+schema.parse.constant {
+  data = $input.version
+  schema = {
+    value: "2.0",
+    error_message: "Only API version 2.0 is supported"
+  }
+}
+```
+
+---
+
+## schema.parse.enum
+
+Validate that a value is one of allowed options.
+
+```xs
+schema.parse.enum {
+  data = $input.status
+  schema = {
+    values: ["pending", "active", "suspended", "closed"],
+    error_message: "Invalid status value"
+  }
+} as $status
+```
+
+### With Default
+
+```xs
+schema.parse.enum {
+  data = $input.priority
+  schema = {
+    values: ["low", "medium", "high"],
+    default: "medium"
+  }
+} as $priority
+```
+
+---
+
+## schema.parse.immutable
+
+Parse a structure that cannot be modified after parsing.
+
+```xs
+schema.parse.immutable {
+  data = $input.config
+  schema = {
+    api_version: { type: "text", required: true },
+    features: { type: "array", items: { type: "text" } }
+  }
+} as $config
+
+// Attempting to modify $config will throw an error
+```
+
+---
+
+## Dynamic Schema Generation
+
+Build schemas programmatically.
+
+```xs
+function "validate_dynamic_form" {
+  input {
+    object form_config
+    object form_data
+  }
+  stack {
+    // Build schema from configuration
+    var $schema { value = { type: "object", properties: {} } }
+
+    foreach ($input.form_config.fields) {
+      each as $field {
+        var.update $schema.properties {
+          value = $schema.properties|set:$field.name:{
+            type: $field.type,
+            required: $field.required,
+            filters: $field.filters
+          }
+        }
+      }
+    }
+
+    // Validate form data against dynamic schema
+    schema.parse.object {
+      data = $input.form_data
+      schema = $schema.properties
+    } as $validated
+  }
+  response = $validated
+}
+```
+
+---
+
+## Error Handling
+
+Schema validation errors can be caught and handled.
+
+```xs
+try_catch {
+  try {
+    schema.parse.object {
+      data = $input.payload
+      schema = $expected_schema
+    } as $validated
+  }
+  catch {
+    // $error contains validation details
+    // $error.field - which field failed
+    // $error.message - validation error message
+    // $error.value - the invalid value
+    throw {
+      name = "ValidationError"
+      value = {
+        field: $error.field,
+        message: $error.message
+      }
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Define schemas upfront** - Use input blocks when structure is known
+2. **Use schema.parse for dynamic data** - External APIs, user-generated content
+3. **Validate at boundaries** - Parse external input, trust internal data
+4. **Provide clear error messages** - Use error_message for user-facing errors
+5. **Use immutable for config** - Prevent accidental modification