gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/2-05-permissions.md

@@ -0,0 +1,497 @@
+---
+id: permissions
+title: "Permissions System"
+description: "Role-based access control implementation"
+icon: Shield
+category: dev
+part: 2
+---
+
+# Permissions System
+
+Role-based access control implementation
+
+## Overview
+
+Gufi implements a comprehensive permission system with multiple layers:
+
+1. **Platform Roles** - Global access (admin, consultant, client)
+2. **Company Roles** - Per-company access (Admin, Manager, User, custom)
+3. **Entity Permissions** - CRUD operations per entity
+4. **Field Permissions** - View/edit per field
+5. **Record Permissions** - Row-level security
+
+## Permission Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Permission Layers                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                  Platform Role                        │  │
+│  │         (admin / consultant / client)                │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                  Company Roles                        │  │
+│  │         (Admin / Manager / Custom...)                │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │               Entity Permissions                      │  │
+│  │         (view / create / edit / delete)              │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                Field Permissions                      │  │
+│  │              (view / edit per field)                 │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │               Record Permissions                      │  │
+│  │         (all / own / team / custom rules)            │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Platform Roles
+
+### Definition
+
+Stored in `core.users.platform_role`:
+
+```sql
+ALTER TABLE core.users ADD COLUMN platform_role VARCHAR(20)
+  DEFAULT 'client'
+  CHECK (platform_role IN ('admin', 'consultant', 'client'));
+```
+
+### Access Matrix
+
+| Feature | admin | consultant | client |
+|---|---|---|---|
+| Company Management | ✓ | ✗ | ✗ |
+| Global Users | ✓ | ✗ | ✗ |
+| Developer Center | ✓ | ✓ | ✗ |
+| Marketplace Admin | ✓ | ✓ | ✗ |
+| API Keys | ✓ | ✓ | ✗ |
+| Environment Variables | ✓ | ✓ | ✗ |
+
+### Frontend Hook
+
+```typescript
+import { usePlatformRole } from '@/hooks/usePlatformRole';
+
+function AdminPanel() {
+  const {
+    platformRole,
+    isAdmin,
+    isConsultant,
+    canAccessDeveloperCenter,
+    canAccessCompanies
+  } = usePlatformRole();
+
+  if (!isAdmin) {
+    return <NotAuthorized />;
+  }
+
+  return <AdminDashboard />;
+}
+```
+
+### Backend Middleware
+
+```javascript
+const requirePlatformAdmin = (req, res, next) => {
+  if (req.user?.platform_role !== 'admin') {
+    return res.status(403).json({
+      error: 'Platform admin access required'
+    });
+  }
+  next();
+};
+
+// Usage
+router.get('/admin/companies', requirePlatformAdmin, getCompanies);
+```
+
+## Company Roles
+
+### Definition
+
+Stored in `core.company_users.roles` (JSONB array):
+
+```json
+["Admin", "Sales Manager", "Support"]
+```
+
+### Default Roles
+
+| Role | Description | Typical Permissions |
+|---|---|---|
+| Admin | Full access | All operations on all entities |
+| Manager | Operational access | CRUD on most entities, limited settings |
+| User | Standard access | Create/edit own records |
+| Viewer | Read-only | View only |
+
+### Custom Roles
+
+Companies can create custom roles:
+
+```javascript
+// Create custom role
+POST /api/companies/:id/roles
+{
+  "name": "Sales Representative",
+  "permissions": {
+    "entities": {
+      "customers": ["view", "create", "edit"],
+      "orders": ["view", "create"],
+      "products": ["view"]
+    }
+  }
+}
+```
+
+## Entity Permissions
+
+### Permission Types
+
+| Permission | Description | Operations |
+|---|---|---|
+| view | Can see entity and records | GET |
+| create | Can add new records | POST |
+| edit | Can modify records | PUT |
+| delete | Can remove records | DELETE |
+| export | Can export data | GET + file |
+| import | Can bulk import | POST + file |
+
+### Configuration
+
+```json
+{
+  "roles": {
+    "Sales Rep": {
+      "entities": {
+        "customers": {
+          "permissions": ["view", "create", "edit"],
+          "recordAccess": "own"
+        },
+        "products": {
+          "permissions": ["view"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Backend Enforcement
+
+```javascript
+const checkEntityPermission = async (req, res, next) => {
+  const { entityId } = req.params;
+  const { user } = req;
+  const operation = getOperationType(req.method);
+
+  const hasPermission = await hasEntityPermission(
+    user.id,
+    req.companyId,
+    entityId,
+    operation
+  );
+
+  if (!hasPermission) {
+    return res.status(403).json({
+      error: `No ${operation} permission for this entity`
+    });
+  }
+
+  next();
+};
+```
+
+## Field Permissions
+
+### Configuration
+
+```json
+{
+  "Sales Rep": {
+    "entities": {
+      "customers": {
+        "fields": {
+          "name": ["view", "edit"],
+          "email": ["view", "edit"],
+          "internal_notes": [],
+          "credit_limit": ["view"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Backend Enforcement
+
+```javascript
+// Filter fields on read
+const filterResponseFields = (data, allowedFields) => {
+  return Object.keys(data).reduce((acc, key) => {
+    if (allowedFields.includes(key) || isSystemField(key)) {
+      acc[key] = data[key];
+    }
+    return acc;
+  }, {});
+};
+
+// Validate fields on write
+const validateWriteFields = (data, editableFields) => {
+  const invalidFields = Object.keys(data).filter(
+    key => !editableFields.includes(key) && !isSystemField(key)
+  );
+
+  if (invalidFields.length > 0) {
+    throw new ForbiddenError(
+      `Cannot edit fields: ${invalidFields.join(', ')}`
+    );
+  }
+};
+```
+
+## Record-Level Security
+
+### Access Types
+
+| Type | Description |
+|---|---|
+| all | Can access all records |
+| own | Only records created by user |
+| team | Records from same team |
+| custom | Based on field conditions |
+
+### Implementation
+
+```sql
+-- Row-level security policy
+CREATE POLICY user_owns_record ON orders
+  FOR ALL
+  USING (created_by = current_setting('app.user_id')::int);
+
+-- Team-based access
+CREATE POLICY team_access ON orders
+  FOR ALL
+  USING (
+    team_id IN (
+      SELECT team_id FROM team_members
+      WHERE user_id = current_setting('app.user_id')::int
+    )
+  );
+```
+
+### Custom Rules
+
+```json
+{
+  "Sales Rep": {
+    "entities": {
+      "orders": {
+        "recordAccess": {
+          "type": "custom",
+          "conditions": {
+            "OR": [
+              { "assigned_to": "@currentUser" },
+              { "region": "@user.region" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Frontend Permission Checks
+
+### usePermissions Hook
+
+```typescript
+import { usePermissions } from '@/hooks/usePermissions';
+
+function EntityView({ entityId }) {
+  const { can, loading } = usePermissions(entityId);
+
+  if (loading) return <Spinner />;
+
+  return (
+    <div>
+      {can('view') && <DataTable />}
+      {can('create') && <NewButton />}
+      {can('export') && <ExportButton />}
+    </div>
+  );
+}
+```
+
+### Permission Store
+
+```typescript
+import { usePermissionsStore } from '@/stores/permissionsStore';
+
+function Component() {
+  const { hasPermission, checkFieldPermission } = usePermissionsStore();
+
+  const canEdit = hasPermission(entityId, 'edit');
+  const canViewSalary = checkFieldPermission(entityId, 'salary', 'view');
+}
+```
+
+## View Permissions
+
+### View Access Control
+
+Views can have permissions separate from entities:
+
+```json
+{
+  "viewPermissions": {
+    "analytics_dashboard": {
+      "allowedRoles": ["Admin", "Manager"],
+      "denyRoles": []
+    },
+    "employee_salaries": {
+      "allowedRoles": ["Admin", "HR Manager"]
+    }
+  }
+}
+```
+
+### Checking View Access
+
+```typescript
+import { useViewPermissions } from '@/hooks/useViewPermissions';
+
+function ViewGateway({ viewId }) {
+  const { canAccess, loading } = useViewPermissions(viewId);
+
+  if (!canAccess) {
+    return <NotAuthorized />;
+  }
+
+  return <ViewComponent />;
+}
+```
+
+## API Permission Patterns
+
+### Resource ID Format
+
+Permissions use Resource IDs (RIDs):
+
+```
+view:{type}:{entity_id}
+
+Examples:
+- view:customers:4589
+- edit:orders:4590
+- delete:products:4591
+```
+
+### Permission Check Endpoint
+
+```http
+GET /api/permissions/check?resource=view:customers:4589
+
+Response:
+{
+  "allowed": true,
+  "reason": "Role 'Admin' grants this permission"
+}
+```
+
+### Bulk Permission Check
+
+```http
+POST /api/permissions/check-bulk
+{
+  "resources": [
+    "view:customers:4589",
+    "edit:customers:4589",
+    "delete:customers:4589"
+  ]
+}
+
+Response:
+{
+  "permissions": {
+    "view:customers:4589": true,
+    "edit:customers:4589": true,
+    "delete:customers:4589": false
+  }
+}
+```
+
+## Best Practices
+
+### Least Privilege
+
+```typescript
+// Good: Check specific permission
+if (can('edit', { recordId: record.id })) {
+  showEditButton();
+}
+
+// Bad: Check broad role
+if (userRole === 'Admin') {
+  showEditButton();
+}
+```
+
+### Consistent Enforcement
+
+```javascript
+// Always check on both frontend AND backend
+
+// Frontend (UX)
+{can('delete') && <DeleteButton />}
+
+// Backend (security)
+router.delete('/:id', checkPermission('delete'), deleteRecord);
+```
+
+### Cache Invalidation
+
+```typescript
+// Invalidate on role changes
+const onRoleChange = async (userId) => {
+  await invalidatePermissionCache(userId);
+  notifyUser(userId, 'permissions_changed');
+};
+```
+
+### Audit Permission Changes
+
+```javascript
+// Log all permission modifications
+const updatePermissions = async (roleId, newPermissions) => {
+  const oldPermissions = await getPermissions(roleId);
+
+  await db.query(
+    'UPDATE roles SET permissions = $1 WHERE id = $2',
+    [newPermissions, roleId]
+  );
+
+  await auditLog('PERMISSIONS_CHANGED', {
+    roleId,
+    before: oldPermissions,
+    after: newPermissions,
+    changedBy: currentUser.id
+  });
+};
+```

package/docs/dev-guide/2-06-integrations-overview.md

@@ -0,0 +1,104 @@
+---
+id: integrations-overview
+title: "Integrations Overview"
+description: "Connect automations to external services"
+icon: Plug
+category: dev
+part: 2
+group: integrations
+---
+
+# Integrations Overview
+
+Connect automations to external services
+
+## What are Integrations?
+
+Integrations let your automations communicate with external APIs. Gufi provides:
+
+- **Built-in connectors**: Stripe, Nayax, OurVend, TNS
+- **Custom HTTP**: Connect to any REST API with `gufi.http()`
+
+## How They Work
+
+```
+Trigger → Automation Script → api.integration.method() → External Service
+                ↓
+         context.env.API_KEY
+```
+
+1. An event triggers your automation (insert, update, click, scheduled)
+2. Your script calls an integration method: `gufi.integrations.stripe.createCheckoutSession()`
+3. Credentials come from environment variables: `env.STRIPE_SECRET_KEY`
+4. The integration communicates with the external service
+
+## Setting Up Credentials
+
+All credentials are stored as **Environment Variables**:
+
+1. Go to **Settings → Environment Variables**
+2. Click **Add Variable**
+3. Enter name (e.g., `STRIPE_SECRET_KEY`) and value
+4. Access in automations via `context.env`
+
+```javascript
+async function my_automation(gufi) {
+  const { env } = gufi.context;
+
+  // Your credentials
+  const stripeKey = env.STRIPE_SECRET_KEY;
+  const nayaxToken = env.NAYAX_TOKEN;
+}
+```
+
+:::warning
+Never hardcode credentials in scripts. Always use environment variables.
+:::
+
+## Available Built-in Integrations
+
+| Integration | Category | Use Case |
+|-------------|----------|----------|
+| **Stripe** | Payments | Create checkout sessions, process payments |
+| **Nayax** | Vending | Sync machines, products, sales, alerts |
+| **OurVend** | Vending | RedPanda vending machine system |
+| **TNS** | Accounting | Colombian product catalog |
+
+Each integration is documented in detail in the following sections.
+
+## Custom HTTP for Any API
+
+For services without built-in integrations, use `gufi.http()`:
+
+```javascript
+const response = await gufi.http({
+  url: 'https://api.example.com/endpoint',
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer ' + env.API_KEY
+  },
+  body: { data: 'value' }
+});
+```
+
+See the **Custom HTTP** section for full documentation.
+
+## Viewing Integrations
+
+**From CLI:**
+
+```bash
+gufi integrations              # List all
+gufi integrations stripe       # Details for Stripe
+```
+
+**From MCP:**
+
+```
+gufi_automation_integrations()
+gufi_automation_integrations({ name: 'stripe' })
+```
+
+**From UI:**
+
+Go to **Settings → Integrations** to see available connectors.