@xano/developer-mcp 1.0.1 → 1.0.2

package/xanoscript_docs/ephemeral.md

@@ -0,0 +1,333 @@
+---
+applyTo: "ephemeral/**/*.xs"
+---
+
+# Ephemeral Environments
+
+Temporary Xano workspaces for testing and one-off operations.
+
+## Quick Reference
+
+| Type | Purpose | Lifecycle |
+|------|---------|-----------|
+| **Service** | Temporary workspace with DB/APIs | Runs until shut down |
+| **Job** | One-time operation | Executes once, then shuts down |
+
+### Directory Structure
+```
+ephemeral/
+├── my-service/
+│   ├── workspace.xs
+│   ├── tables/
+│   ├── functions/
+│   └── apis/
+└── my-job/
+    ├── workspace.xs
+    ├── tables/
+    └── functions/
+```
+
+---
+
+## Ephemeral Service
+
+A temporary workspace with database, functions, and API endpoints.
+
+### workspace.xs
+```xs
+workspace my_service {
+  env = {
+    api_key: "test-key"
+    debug: "true"
+  }
+}
+```
+
+### Table with Seed Data
+```xs
+table event {
+  auth = false
+  schema {
+    int id
+    timestamp created_at?=now
+    text name filters=trim
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Event 1"}
+    {"id": 2, "name": "Event 2"}
+  ]
+}
+```
+
+### API Group
+```xs
+api_group events {
+  canonical = "events-api"
+}
+```
+
+### Endpoints
+```xs
+query list verb=GET {
+  api_group = "events"
+  stack {
+    db.query event {
+      return = { type: "list" }
+    } as $events
+  }
+  response = $events
+}
+
+query add verb=POST {
+  api_group = "events"
+  input { text name filters=trim }
+  stack {
+    db.add event {
+      data = { name: $input.name }
+    } as $event
+  }
+  response = $event
+}
+```
+
+---
+
+## Ephemeral Job
+
+One-time operation with setup and cleanup hooks.
+
+### Reserved Functions
+| Function | Purpose | Required |
+|----------|---------|----------|
+| `$main` | Primary logic | Yes |
+| `$pre` | Setup/validation | No |
+| `$post` | Cleanup/notification | No |
+
+### Execution Order
+1. `$pre` (if defined)
+2. `$main`
+3. `$post` (if defined)
+4. Environment shuts down
+
+### $main Function
+```xs
+function "$main" {
+  input {
+    json args                   # Runtime arguments
+    json pre                    # Result from $pre
+  }
+  stack {
+    db.query authors {
+      return = { type: "count" }
+    } as $count
+
+    precondition ($count > 0) {
+      error = "No authors found"
+    }
+
+    db.add authors {
+      data = { name: "New Author" }
+    }
+  }
+  response = { processed: true }
+}
+```
+
+### $pre Function (optional)
+```xs
+function "$pre" {
+  input { json args }
+  stack {
+    // Validation or setup
+    precondition ($input.args.required_field != null) {
+      error = "Missing required field"
+    }
+  }
+  response = { validated: true }
+}
+```
+
+### $post Function (optional)
+```xs
+function "$post" {
+  input {
+    json args
+    json pre
+    json main
+  }
+  stack {
+    // Send notification or cleanup
+    api.request {
+      url = $env.WEBHOOK_URL
+      method = "POST"
+      params = {
+        status: "complete",
+        result: $input.main
+      }
+    }
+  }
+  response = null
+}
+```
+
+---
+
+## Complete Service Example
+
+```
+ephemeral/event-tracker/
+├── workspace.xs
+├── tables/
+│   └── event.xs
+└── apis/
+    ├── api_group.xs
+    ├── list.xs
+    ├── add.xs
+    └── clear.xs
+```
+
+### workspace.xs
+```xs
+workspace event_tracker {
+  env = { api_key: "test" }
+}
+```
+
+### tables/event.xs
+```xs
+table event {
+  auth = false
+  schema {
+    int id
+    timestamp created_at?=now
+    text name
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = []
+}
+```
+
+### apis/list.xs
+```xs
+query list verb=GET {
+  api_group = "events"
+  stack {
+    db.query event {
+      sort = { created_at: "desc" }
+      return = { type: "list" }
+    } as $events
+  }
+  response = $events
+}
+```
+
+---
+
+## Complete Job Example
+
+```
+ephemeral/data-migration/
+├── workspace.xs
+├── tables/
+│   └── users.xs
+└── functions/
+    ├── $main.xs
+    └── $post.xs
+```
+
+### workspace.xs
+```xs
+workspace data_migration {
+  env = { webhook_url: "https://webhook.site/xxx" }
+}
+```
+
+### tables/users.xs
+```xs
+table users {
+  auth = false
+  schema {
+    int id
+    text name
+    text email
+    timestamp migrated_at?
+  }
+  index = [
+    {type: "primary", field: [{name: "id"}]}
+  ]
+  items = [
+    {"id": 1, "name": "Alice", "email": "alice@example.com"}
+    {"id": 2, "name": "Bob", "email": "bob@example.com"}
+  ]
+}
+```
+
+### functions/$main.xs
+```xs
+function "$main" {
+  input { json args, json pre }
+  stack {
+    db.query users {
+      where = $db.users.migrated_at == null
+    } as $pending
+
+    foreach ($pending) {
+      each as $user {
+        db.edit users {
+          field_name = "id"
+          field_value = $user.id
+          data = { migrated_at: now }
+        }
+      }
+    }
+  }
+  response = { migrated: $pending|count }
+}
+```
+
+### functions/$post.xs
+```xs
+function "$post" {
+  input { json args, json pre, json main }
+  stack {
+    api.request {
+      url = $env.webhook_url
+      method = "POST"
+      params = { result: $input.main }
+    }
+  }
+  response = null
+}
+```
+
+---
+
+## Deploying
+
+### Deploy Service
+```
+publish_ephemeral_service name="my-api" directory="ephemeral/my-service" mode="service"
+```
+
+### Run Job
+```
+publish_ephemeral_service name="migration" directory="ephemeral/my-job" mode="job"
+```
+
+---
+
+## Best Practices
+
+1. **Keep isolated** - Self-contained with own tables/functions
+2. **Seed test data** - Use `items` in table definitions
+3. **Use environment variables** - Store config in workspace `env`
+4. **Handle cleanup** - Use `$post` for notifications/cleanup
+5. **Validate in $pre** - Check preconditions before main logic
+6. **Use preconditions** - Verify expected outcomes in jobs
+7. **Name clearly** - Indicate purpose: `auth-test`, `data-migration`
+8. **Set end dates** - Use `ends_on` for temporary schedules

package/xanoscript_docs/frontend.md

@@ -0,0 +1,291 @@
+---
+applyTo: "static/**/*"
+---
+
+# Frontend
+
+Static frontend development and Lovable/Supabase migration.
+
+## Quick Reference
+
+### Directory Structure
+```
+static/
+├── index.html              # Main entry point
+├── css/
+├── js/
+│   └── api.js              # Centralized API calls
+└── assets/
+```
+
+### Key Tools
+| Tool | Purpose |
+|------|---------|
+| `get_xano_api_specifications` | Get OpenAPI specs before frontend work |
+| `upload_static_files_to_xano` | Deploy to Xano CDN |
+
+---
+
+## Base Template
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>My App</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet">
+  <script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
+</head>
+<body>
+  <div id="app"></div>
+  <script src="js/api.js"></script>
+  <script src="js/app.js"></script>
+</body>
+</html>
+```
+
+---
+
+## API Client
+
+### Basic Setup (api.js)
+```javascript
+const API_BASE = 'https://your-instance.xano.io/api:group';
+
+async function apiCall(endpoint, options = {}) {
+  const token = localStorage.getItem('auth_token');
+  const headers = {
+    'Content-Type': 'application/json',
+    ...(token && { 'Authorization': `Bearer ${token}` })
+  };
+
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    ...options,
+    headers: { ...headers, ...options.headers }
+  });
+
+  if (!response.ok) {
+    throw new Error(`API Error: ${response.status}`);
+  }
+
+  return response.json();
+}
+
+// CRUD helpers
+const api = {
+  get: (endpoint) => apiCall(endpoint),
+  post: (endpoint, data) => apiCall(endpoint, {
+    method: 'POST',
+    body: JSON.stringify(data)
+  }),
+  patch: (endpoint, data) => apiCall(endpoint, {
+    method: 'PATCH',
+    body: JSON.stringify(data)
+  }),
+  delete: (endpoint) => apiCall(endpoint, { method: 'DELETE' })
+};
+```
+
+---
+
+## Authentication
+
+### Login
+```javascript
+async function login(email, password) {
+  const { authToken } = await api.post('/auth/login', { email, password });
+  localStorage.setItem('auth_token', authToken);
+  return authToken;
+}
+```
+
+### Signup
+```javascript
+async function signup(email, password, name) {
+  const { authToken } = await api.post('/auth/signup', {
+    email, password, name
+  });
+  localStorage.setItem('auth_token', authToken);
+  return authToken;
+}
+```
+
+### Logout
+```javascript
+function logout() {
+  localStorage.removeItem('auth_token');
+  window.location.href = '/login.html';
+}
+```
+
+### Get Current User
+```javascript
+async function getCurrentUser() {
+  return api.get('/auth/me');
+}
+```
+
+---
+
+## Lovable Migration
+
+Migrate from Supabase to Xano using the compatibility SDK.
+
+### 1. Install SDK
+```bash
+npm install @xano/supabase-compat
+```
+
+### 2. Create Xano Client
+```typescript
+// src/integrations/xano/client.ts
+import { createClient } from '@xano/supabase-compat';
+
+export const xano = createClient(
+  import.meta.env.VITE_XANO_URL,
+  import.meta.env.VITE_XANO_AUTH_ENDPOINT,
+  {
+    auth: {
+      storage: localStorage,
+      persistSession: true,
+      autoRefreshToken: true
+    }
+  }
+);
+```
+
+### 3. Update Environment
+```env
+VITE_XANO_URL=https://your-instance.xano.io
+VITE_XANO_AUTH_ENDPOINT=/api:groupId/auth
+```
+
+### 4. Update Auth Hooks
+
+Before (Supabase):
+```typescript
+import { supabase } from '@/integrations/supabase/client';
+
+supabase.auth.signInWithPassword({ email, password });
+supabase.auth.signUp({ email, password });
+supabase.auth.signOut();
+```
+
+After (Xano):
+```typescript
+import { xano } from '@/integrations/xano/client';
+
+xano.auth.signInWithPassword({ email, password });
+xano.auth.signUp({ email, password });
+xano.auth.signOut();
+```
+
+### 5. Update Data Hooks
+
+Before (Supabase):
+```typescript
+const { data, error } = await supabase
+  .from('products')
+  .select('*')
+  .eq('category', 'electronics')
+  .order('created_at', { ascending: false });
+```
+
+After (Xano):
+```typescript
+const { data, error } = await xano
+  .endpoint('/api:group/products')
+  .get({
+    category: 'electronics',
+    sort: 'created_at',
+    order: 'desc'
+  });
+```
+
+---
+
+## Common Patterns
+
+### Pagination
+```javascript
+async function getProducts(page = 1, perPage = 20) {
+  return api.get(`/products?page=${page}&per_page=${perPage}`);
+}
+```
+
+### Filtering
+```javascript
+async function searchProducts(query, category) {
+  const params = new URLSearchParams();
+  if (query) params.append('query', query);
+  if (category) params.append('category', category);
+  return api.get(`/products?${params}`);
+}
+```
+
+### File Upload
+```javascript
+async function uploadImage(file) {
+  const formData = new FormData();
+  formData.append('image', file);
+
+  const response = await fetch(`${API_BASE}/upload`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${localStorage.getItem('auth_token')}`
+    },
+    body: formData
+  });
+
+  return response.json();
+}
+```
+
+---
+
+## Migration Checklist
+
+### Backend (Xano)
+- [ ] Create tables matching Supabase schema
+- [ ] Create CRUD endpoints for each resource
+- [ ] Set up authentication endpoints
+- [ ] Push changes: `push_all_changes_to_xano`
+- [ ] Get API specs: `get_xano_api_specifications`
+
+### Frontend
+- [ ] Install `@xano/supabase-compat`
+- [ ] Create Xano client
+- [ ] Update environment variables
+- [ ] Update auth hooks (minimal changes)
+- [ ] Update data fetching (table → endpoint)
+- [ ] Test all operations
+- [ ] Remove Supabase dependencies
+
+---
+
+## Deployment
+
+Deploy static files to Xano CDN:
+
+```
+invoke upload_static_files_to_xano
+```
+
+The tool will:
+1. Bundle files from `static/`
+2. Upload to Xano CDN
+3. Return hosted URL
+
+---
+
+## Best Practices
+
+1. **Get API specs first** - Use `get_xano_api_specifications` before coding
+2. **Centralize API calls** - Single `api.js` file
+3. **Handle errors** - Show user-friendly messages
+4. **Store tokens securely** - localStorage for web, secure storage for mobile
+5. **Validate before submit** - Client-side validation before API calls
+6. **Use loading states** - Show progress during API calls
+7. **Test incrementally** - Migrate one feature at a time