gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/2-01-api-reference.md

@@ -0,0 +1,564 @@
+---
+id: api-reference
+title: "API Reference"
+description: "Complete REST API documentation"
+icon: Code
+category: dev
+part: 2
+---
+
+# API Reference
+
+Complete REST API documentation
+
+## Base URL
+
+```
+Production: https://api.gogufi.com/api
+Development: http://localhost:3000/api
+```
+
+## Authentication
+
+### Login
+
+```http
+POST /auth/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "your_password"
+}
+```
+
+**Response:**
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIs...",
+  "user": {
+    "id": 123,
+    "email": "user@example.com",
+    "name": "John Doe"
+  }
+}
+```
+
+Also sets HttpOnly refresh cookie.
+
+### Using Authentication
+
+Include token in Authorization header:
+
+```http
+GET /api/tables/products
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+X-Company-ID: 146
+```
+
+### Refresh Token
+
+```http
+POST /auth/refresh
+Cookie: refresh_token=...
+```
+
+Returns new access token.
+
+## Company Context
+
+Most endpoints require company context:
+
+```http
+X-Company-ID: 146
+```
+
+This header specifies which company's data to access.
+
+## CRUD Operations
+
+### List Records
+
+```http
+GET /tables/:tableId
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| page | number | Page number (default: 1) |
+| pageSize | number | Records per page (default: 20, max: 100) |
+| sort | string | Sort field |
+| order | string | asc or desc |
+| filter | object | Filter conditions (JSON) |
+| search | string | Full-text search |
+
+**Example:**
+```http
+GET /tables/products?page=1&pageSize=20&sort=created_at&order=desc
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "name": "Widget Pro",
+      "price": { "currency": "EUR", "amount": 99.99 },
+      "stock": 150,
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 5
+  }
+}
+```
+
+### Get Single Record
+
+```http
+GET /tables/:tableId/:rowId
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "id": 1,
+    "name": "Widget Pro",
+    "price": { "currency": "EUR", "amount": 99.99 },
+    "stock": 150,
+    "category": {
+      "id": 5,
+      "name": "Electronics"
+    },
+    "created_at": "2024-01-15T10:30:00Z",
+    "updated_at": "2024-01-16T14:20:00Z"
+  }
+}
+```
+
+### Create Record
+
+```http
+POST /tables/:tableId
+Content-Type: application/json
+
+{
+  "name": "New Product",
+  "price": { "currency": "EUR", "amount": 49.99 },
+  "stock": 100,
+  "category": 5
+}
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "id": 101,
+    "name": "New Product",
+    ...
+  }
+}
+```
+
+### Update Record
+
+```http
+PUT /tables/:tableId/:rowId
+Content-Type: application/json
+
+{
+  "price": { "currency": "EUR", "amount": 59.99 },
+  "stock": 80
+}
+```
+
+Only include fields you want to update.
+
+### Delete Record
+
+```http
+DELETE /tables/:tableId/:rowId
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Record deleted"
+}
+```
+
+## Filtering
+
+### Simple Filters
+
+```http
+GET /tables/products?filter={"status":"active"}
+```
+
+### Comparison Operators
+
+```json
+{
+  "price": { "$gt": 100 },
+  "stock": { "$lte": 50 },
+  "status": { "$ne": "archived" }
+}
+```
+
+| Operator | Description |
+|---|---|
+| $eq | Equals (default) |
+| $ne | Not equals |
+| $gt | Greater than |
+| $gte | Greater or equal |
+| $lt | Less than |
+| $lte | Less or equal |
+| $in | In array |
+| $nin | Not in array |
+| $like | Pattern match |
+| $null | Is null |
+
+### Complex Filters
+
+```json
+{
+  "$and": [
+    { "status": "active" },
+    { "price": { "$gt": 100 } }
+  ]
+}
+```
+
+```json
+{
+  "$or": [
+    { "status": "urgent" },
+    { "priority": "high" }
+  ]
+}
+```
+
+### Date Filters
+
+```json
+{
+  "created_at": {
+    "$gte": "2024-01-01",
+    "$lt": "2024-02-01"
+  }
+}
+```
+
+## Bulk Operations
+
+### Bulk Create
+
+```http
+POST /tables/:tableId/bulk
+Content-Type: application/json
+
+{
+  "records": [
+    { "name": "Product 1", "price": 10 },
+    { "name": "Product 2", "price": 20 },
+    { "name": "Product 3", "price": 30 }
+  ]
+}
+```
+
+### Bulk Update
+
+```http
+PUT /tables/:tableId/bulk
+Content-Type: application/json
+
+{
+  "ids": [1, 2, 3],
+  "data": {
+    "status": "archived"
+  }
+}
+```
+
+### Bulk Delete
+
+```http
+DELETE /tables/:tableId/bulk
+Content-Type: application/json
+
+{
+  "ids": [1, 2, 3]
+}
+```
+
+## Module & Entity Endpoints
+
+### List Modules
+
+```http
+GET /modules?company_id=146
+```
+
+### Get Module
+
+```http
+GET /modules/:moduleId
+```
+
+### List Entities
+
+```http
+GET /entities?module_id=360
+```
+
+### Get Entity
+
+```http
+GET /entities/:entityId
+```
+
+### Get Company Schema
+
+```http
+GET /companies/:companyId/schema
+```
+
+Returns complete schema including all modules and entities.
+
+## File Upload
+
+### Upload File
+
+```http
+POST /upload
+Content-Type: multipart/form-data
+
+file: (binary)
+```
+
+**Response:**
+```json
+{
+  "url": "https://storage.gufi.com/files/abc123.pdf",
+  "name": "document.pdf",
+  "mime": "application/pdf",
+  "size": 245678
+}
+```
+
+### Upload Image
+
+```http
+POST /upload/image
+Content-Type: multipart/form-data
+
+file: (binary)
+```
+
+Also generates thumbnail.
+
+## Automations
+
+### Run Click Automation
+
+```http
+POST /automations/click
+Content-Type: application/json
+
+{
+  "company_id": 146,
+  "module_id": 360,
+  "table_id": 4589,
+  "function_name": "send_email",
+  "table_name": "orders",
+  "input": {
+    "record_id": 123,
+    "template": "order_confirmation"
+  }
+}
+```
+
+### Get Automation Scripts
+
+```http
+GET /automations/scripts?company_id=146
+```
+
+### Get Execution History
+
+```http
+GET /automations/executions?company_id=146&limit=50
+```
+
+## Webhooks
+
+### Entity Webhooks
+
+When webhooks are enabled for an entity:
+
+```http
+GET /webhook/e/:entityId/:token
+POST /webhook/e/:entityId/:token
+PUT /webhook/e/:entityId/:token/:rowId
+DELETE /webhook/e/:entityId/:token/:rowId
+```
+
+No authentication required (token in URL provides access).
+
+## Error Responses
+
+### Error Format
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": {
+      "field": "email",
+      "reason": "Invalid email format"
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | HTTP Status | Description |
+|---|---|---|
+| UNAUTHORIZED | 401 | Invalid or missing token |
+| FORBIDDEN | 403 | No permission |
+| NOT_FOUND | 404 | Resource not found |
+| VALIDATION_ERROR | 400 | Invalid input |
+| CONFLICT | 409 | Duplicate or conflict |
+| INTERNAL_ERROR | 500 | Server error |
+
+## Rate Limiting
+
+| Tier | Limit |
+|---|---|
+| Standard | 100 requests/minute |
+| Pro | 500 requests/minute |
+| Enterprise | Custom |
+
+Rate limit headers:
+
+```http
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1699999999
+```
+
+## Pagination
+
+### Offset-Based (Default)
+
+```http
+GET /tables/products?page=2&pageSize=20
+```
+
+### Keyset Pagination (Large Datasets)
+
+```http
+GET /tables/products?after_id=1000&limit=20
+```
+
+More efficient for large tables.
+
+## Field-Specific Formats
+
+### Currency Input
+
+```json
+{
+  "price": {
+    "currency": "EUR",
+    "amount": 150.00
+  }
+}
+```
+
+### Phone Input
+
+```json
+{
+  "phone": {
+    "prefix": "+34",
+    "number": "612345678"
+  }
+}
+```
+
+### Location Input
+
+```json
+{
+  "address": {
+    "street": "Calle Mayor",
+    "number": "15",
+    "city": "Madrid",
+    "country": "Spain",
+    "postal_code": "28013"
+  }
+}
+```
+
+### File Input
+
+First upload file, then use returned URL:
+
+```json
+{
+  "document": {
+    "url": "https://storage.gufi.com/...",
+    "name": "contract.pdf",
+    "mime": "application/pdf",
+    "size": 245678
+  }
+}
+```
+
+## SDK Usage
+
+### JavaScript/TypeScript
+
+```typescript
+import { GufiClient } from '@gufi/sdk';
+
+const client = new GufiClient({
+  baseUrl: 'https://api.gogufi.com',
+  token: 'your_token',
+  companyId: 146
+});
+
+// List products
+const products = await client.tables.list('products', {
+  filter: { status: 'active' },
+  page: 1,
+  pageSize: 20
+});
+
+// Create product
+const newProduct = await client.tables.create('products', {
+  name: 'New Widget',
+  price: { currency: 'EUR', amount: 99.99 }
+});
+
+// Update product
+await client.tables.update('products', 1, {
+  stock: 50
+});
+
+// Delete product
+await client.tables.delete('products', 1);
+```