@xano/developer-mcp 1.0.33 → 1.0.35

package/dist/xanoscript_docs/README.md

@@ -108,7 +108,20 @@ $db.table.field     // Database field reference (in queries)
 $this               // Current item in loops/maps
 ```
 
-**Note:** `$response` is a reserved word and cannot be used as a variable name.
+**Reserved Variables:** The following cannot be used as variable names: `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`.
+
+### Type Names
+
+XanoScript uses specific type names:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | String (not "string") | `text name` |
+| `int` | Integer (not "integer") | `int count` |
+| `bool` | Boolean (not "boolean") | `bool active` |
+| `decimal` | Float/number | `decimal price` |
+| `type[]` | Array (not "array" or "list") | `text[] tags` |
+| `json` | Arbitrary JSON data | `json metadata` |
 
 ### Comments
 
@@ -142,18 +155,35 @@ applyTo: "function/**/*.xs"
 
 This helps AI tools apply the correct documentation based on the file being edited.
 
+## Getting Started
+
+For common patterns and quick examples, use:
+```
+xanoscript_docs({ topic: "quickstart" })
+```
+
+This includes:
+- Variable declaration patterns
+- Conditional logic (if/elseif/else)
+- API requests with error handling
+- Database CRUD operations
+- Common mistakes to avoid
+
+---
+
 ## Documentation Index
 
 Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 ### Core Language
 
-| Topic       | Description                                       |
-| ----------- | ------------------------------------------------- |
-| `syntax`    | Expressions, operators, filters, system variables |
-| `types`     | Data types, validation, input blocks              |
-| `functions` | Reusable function stacks, async, loops            |
-| `schema`    | Runtime schema parsing and validation             |
+| Topic        | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| `quickstart` | Common patterns, quick examples, mistakes to avoid   |
+| `syntax`     | Expressions, operators, filters, system variables    |
+| `types`      | Data types, validation, input blocks                 |
+| `functions`  | Reusable function stacks, async, loops               |
+| `schema`     | Runtime schema parsing and validation                |
 
 ### Data
 
@@ -210,3 +240,47 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 | ------------- | ------------------------------------------------------------ |
 | `performance` | Performance optimization best practices                      |
 | `security`    | Security best practices for authentication and authorization |
+
+---
+
+## Example Implementations
+
+Common integration patterns you can reference:
+
+### External API Integrations
+- **OpenAI/ChatGPT**: Use `api.request` with POST to `/v1/chat/completions`
+- **Stripe**: Use `api.request` with form-encoded params for payments
+- **SendGrid/Resend**: Use `api.request` or `util.send_email` for emails
+- **Slack/Discord**: Use `api.request` with webhook URLs
+- **Twilio**: Use `api.request` with Basic auth for SMS
+
+### Common Pattern: API Integration Function
+
+```xs
+function "call_external_api" {
+  input {
+    text endpoint
+    object payload
+  }
+  stack {
+    api.request {
+      url = $env.API_BASE_URL ~ $input.endpoint
+      method = "POST"
+      params = $input.payload
+      headers = [
+        "Content-Type: application/json",
+        "Authorization: Bearer " ~ $env.API_KEY
+      ]
+      timeout = 30
+    } as $api_result
+
+    precondition ($api_result.response.status >= 200 && $api_result.response.status < 300) {
+      error_type = "standard"
+      error = "API error: " ~ ($api_result.response.status|to_text)
+    }
+  }
+  response = $api_result.response.result
+}
+```
+
+For more patterns, see `xanoscript_docs({ topic: "quickstart" })` or `xanoscript_docs({ topic: "integrations" })`.

package/dist/xanoscript_docs/database.md

@@ -612,3 +612,17 @@ try_catch {
 5. **Use null-safe operators** - `==?` for optional filters
 6. **Use bulk operations for batch processing** - More efficient than loops
 7. **Handle deadlocks gracefully** - Implement retry logic for concurrent writes
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `tables` | Database schema definitions with indexes and relationships |
+| `syntax` | Query filters, operators, and expressions |
+| `quickstart` | Common CRUD patterns and examples |
+| `addons` | Reusable subqueries for fetching related data |
+| `performance` | Query optimization best practices |

package/dist/xanoscript_docs/functions.md

@@ -465,3 +465,17 @@ foreach ($items) {
 5. **Keep stacks shallow** - Avoid deeply nested conditionals
 6. **Use group for organization** - Visually group related statements for readability
 7. **Use remove sparingly** - Consider filtering arrays instead
+
+---
+
+## Related Topics
+
+Explore more with `xanoscript_docs({ topic: "<topic>" })`:
+
+| Topic | Description |
+|-------|-------------|
+| `types` | Input types, filters, and validation |
+| `syntax` | Expressions, operators, and control flow |
+| `quickstart` | Common patterns and examples |
+| `database` | Database operations in function stacks |
+| `testing` | Unit testing functions |

package/dist/xanoscript_docs/integrations.md

@@ -575,22 +575,92 @@ util.send_email {
 
 ---
 
-## External APIs
+## External APIs (api.request)
 
 Make HTTP requests to external APIs.
 
+### Quick Reference
+
 ```xs
 api.request {
-  url = "https://api.example.com/data"
-  method = "POST"
-  params = { key: "value" }
+  url = "https://api.example.com/endpoint"
+  method = "POST"                    // GET, POST, PUT, PATCH, DELETE
+  params = $payload                  // Request body for POST/PUT/PATCH
   headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
-  timeout = 30
+  timeout = 30                       // Timeout in seconds
 } as $api_result
+
+// Access response
+$api_result.response.status          // HTTP status code (200, 404, etc.)
+$api_result.response.result          // Response body (auto-parsed JSON)
+$api_result.response.headers         // Response headers array
 ```
 
+> **Important:** The `params` parameter is used for the **request body** (POST/PUT/PATCH), not query parameters. This naming is counterintuitive but consistent across XanoScript.
+
 > **Note:** The `headers` parameter expects an array of text strings, where each string contains the header name and value separated by a colon (e.g., `["Content-Type: application/json", "X-Custom-Header: value"]`).
 
+### GET Request
+
+```xs
+api.request {
+  url = "https://api.example.com/users?page=1&limit=10"
+  method = "GET"
+  headers = ["Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+var $users { value = $api_result.response.result }
+```
+
+### POST Request with JSON Body
+
+```xs
+var $payload {
+  value = {
+    name: $input.name,
+    email: $input.email
+  }
+}
+
+api.request {
+  url = "https://api.example.com/users"
+  method = "POST"
+  params = $payload
+  headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+// Check for success
+precondition ($api_result.response.status == 201) {
+  error_type = "standard"
+  error = "Failed to create user: " ~ ($api_result.response.result|json_encode)
+}
+```
+
+### Error Handling Pattern
+
+```xs
+api.request {
+  url = "https://api.example.com/data"
+  method = "GET"
+  timeout = 30
+} as $api_result
+
+conditional {
+  if ($api_result.response.status >= 200 && $api_result.response.status < 300) {
+    var $data { value = $api_result.response.result }
+  }
+  elseif ($api_result.response.status == 404) {
+    throw { name = "NotFound", value = "Resource not found" }
+  }
+  else {
+    throw {
+      name = "APIError",
+      value = "API returned status " ~ ($api_result.response.status|to_text)
+    }
+  }
+}
+```
+
 ### Response Structure
 
 The `api.request` statement returns an object with both request and response details: