feat: auto-docusaurus-prs

.github/workflows/create-docusaurus-pr.yml

@@ -0,0 +1,55 @@
+name: Update API Documentation
+
+name: Update API Documentation
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'api/docs/**'
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Add permissions for GITHUB_TOKEN
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  create-docs-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source repository
+        uses: actions/checkout@v4
+        with:
+          path: source-repo
+
+      - name: Checkout docs repository
+        uses: actions/checkout@v4
+        with:
+          repository: unraid/docs
+          path: docs-repo
+          token: ${{ github.token }}
+
+      - name: Copy updated docs
+        run: |
+          if [ ! -d "source-repo/api/docs" ]; then
+            echo "Source directory does not exist!"
+            exit 1
+          fi
+          mkdir -p docs-repo/docs/api
+          cp -r source-repo/api/docs/* docs-repo/docs/api/
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ github.token }}
+          path: docs-repo
+          commit-message: 'docs: update API documentation'
+          title: 'Update API Documentation'
+          body: |
+            This PR updates the API documentation based on changes from the main repository.
+
+            Changes were automatically generated from api/docs/* directory.
+          branch: update-api-docs
+          base: main
+          delete-branch: true

api/docs/cli.md

@@ -0,0 +1,161 @@
+# CLI Commands
+
+### Start
+
+```bash
+unraid-api start [--log-level <level>]
+```
+
+Starts the Unraid API service.
+
+- `--log-level`: Optional. Set logging level (trace|debug|info|warn|error)
+
+### Stop
+
+```bash
+unraid-api stop [--delete]
+```
+
+Stops the Unraid API service.
+
+- `--delete`: Optional. Delete the PM2 home directory
+
+### Restart
+
+```bash
+unraid-api restart
+```
+
+Restarts the Unraid API service.
+
+### Logs
+
+```bash
+unraid-api logs [-l <lines>]
+```
+
+View the API logs.
+
+- `-l, --lines`: Optional. Number of lines to tail (default: 100)
+
+## Configuration Commands
+
+### Config
+
+```bash
+unraid-api config
+```
+
+Displays current configuration values.
+
+### Switch Environment
+
+```bash
+unraid-api switch-env [-e <environment>]
+```
+
+Switch between production and staging environments.
+
+- `-e, --environment`: Optional. Target environment (production|staging)
+
+### Developer Mode
+
+```bash
+unraid-api developer
+```
+
+Configure developer features for the API (e.g., GraphQL sandbox).
+
+## API Key Management
+
+### API Key Commands
+
+```bash
+unraid-api apikey [options]
+```
+
+Create and manage API keys.
+
+Options:
+
+- `--name <name>`: Name of the key
+- `--create`: Create a new key
+- `-r, --roles <roles>`: Comma-separated list of roles
+- `-p, --permissions <permissions>`: Comma-separated list of permissions
+- `-d, --description <description>`: Description for the key
+
+## SSO (Single Sign-On) Management
+
+### SSO Base Command
+
+```bash
+unraid-api sso
+```
+
+#### Add SSO User
+
+```bash
+unraid-api sso add-user
+# or
+unraid-api sso add
+# or
+unraid-api sso a
+```
+
+Add a new user for SSO authentication.
+
+#### Remove SSO User
+
+```bash
+unraid-api sso remove-user
+# or
+unraid-api sso remove
+# or
+unraid-api sso r
+```
+
+Remove a user (or all users) from SSO.
+
+#### List SSO Users
+
+```bash
+unraid-api sso list-users
+# or
+unraid-api sso list
+# or
+unraid-api sso l
+```
+
+List all configured SSO users.
+
+#### Validate SSO Token
+
+```bash
+unraid-api sso validate-token <token>
+# or
+unraid-api sso validate
+# or
+unraid-api sso v
+```
+
+Validates an SSO token and returns its status.
+
+## Report Generation
+
+### Generate Report
+
+```bash
+unraid-api report [-r] [-j]
+```
+
+Generate a system report.
+
+- `-r, --raw`: Display raw command output
+- `-j, --json`: Display output in JSON format
+
+## Notes
+
+1. Most commands that modify the system state will require appropriate permissions.
+2. Some commands may require the API to be running or stopped depending on their function.
+3. When using API keys, ensure you store them securely as they provide access to your system.
+4. SSO configuration changes may require a service restart to take effect.

api/docs/feature-implementation.md

@@ -0,0 +1,136 @@
+# Unraid API Project Status
+
+This document outlines the current implementation status of various Unraid components in the API.
+
+## Implementation Status Legend
+
+- ✅ Fully Implemented
+- 🟡 Partially Implemented
+- ❌ Not Implemented
+- 🔒 Requires Authentication
+
+## Core Components
+
+| Component | Read | Write | Update | Notes |
+|-----------|------|-------|--------|-------|
+| Array | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Full array management including start/stop/status |
+| Parity | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Check/pause/resume functionality |
+| Disks | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Comprehensive disk management |
+| Docker | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Container and network management |
+
+## System Information
+
+| Component | Read | Write | Notes |
+|-----------|------|-------|-------|
+| CPU | ✅ | ❌ | Detailed CPU information including cores, cache, flags |
+| Memory | ✅ | ❌ | RAM and swap information |
+| OS | ✅ | ❌ | System version and kernel details |
+| Hardware | ✅ | ❌ | Baseboard and system information |
+| Network | ✅ | 🟡 | Basic network interface information |
+
+## Configuration & Management
+
+| Component | Read | Write | Update | Notes |
+|-----------|------|-------|--------|-------|
+| API Keys | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Full CRUD operations |
+| SSO | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Complete SSO integration |
+| Remote Access | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Dynamic and static access configuration |
+| Display Settings | ✅ 🔒 | 🟡 | 🟡 | Basic display configuration |
+
+## Device Management
+
+| Component | Read | Write | Notes |
+|-----------|------|-------|-------|
+| GPU | ✅ | ❌ | Basic GPU information |
+| USB Devices | ✅ | ❌ | Basic USB device enumeration |
+| PCI Devices | ✅ | ❌ | PCI device information |
+| Storage Devices | ✅ | 🟡 | Comprehensive storage information |
+
+## Security & Authentication
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Role-Based Access | ✅ | Implemented roles: admin, connect, guest |
+| API Key Authentication | ✅ | Full implementation with key management |
+| Permission System | ✅ | Granular resource-based permissions |
+| Rate Limiting | ✅ | Implemented with configurable limits |
+
+## Available Resources
+
+The following resources are available for API access:
+
+```typescript
+enum Resource {
+    api_key
+    array
+    cloud
+    config
+    connect
+    connect__remote_access
+    customizations
+    dashboard
+    disk
+    display
+    docker
+    flash
+    info
+    logs
+    me
+    network
+    notifications
+    online
+    os
+    owner
+    permission
+    registration
+    servers
+    services
+    share
+    vars
+    vms
+    welcome
+}
+```
+
+## Authentication Methods
+
+1. API Key Authentication
+   - Header-based authentication
+   - Role-based access control
+   - Granular permissions
+
+2. Session-based Authentication
+   - Cookie-based authentication
+   - CSRF protection
+   - Integration with Unraid's existing auth system
+
+## Rate Limiting
+
+Current implementation:
+- 100 requests per 10 seconds per IP
+- Configurable through ThrottlerModule
+
+## Development Features
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| GraphQL Sandbox | ✅ | Available in developer mode |
+| CLI Tools | ✅ | Comprehensive command line interface |
+| Error Handling | ✅ | Standardized error responses |
+| Logging | ✅ | Configurable log levels |
+
+## Notes
+
+1. All authenticated endpoints require either:
+   - Valid API key in X-API-Key header
+   - Valid session cookie with CSRF token
+
+2. Resource access is controlled by:
+   - User roles
+   - Individual permissions
+   - Resource-specific policies
+
+3. The API implements standard GraphQL features:
+   - Queries for reading data
+   - Mutations for writing/updating data
+   - Subscriptions for real-time updates