nextcloud-integration/skills/nextcloud-capabilities/SKILL.md

# Nextcloud Capabilities Skill

**Purpose:** Query Nextcloud server capabilities, version, and available apps.

## Overview

This skill provides access to the Nextcloud Capabilities API (OCS endpoint). Capabilities are useful for:
- Detecting server version
- Checking which apps are installed
- Validating feature availability before using app-specific APIs
- Theming information (colors, logos)

## Prerequisites

- Nextcloud server URL
- Username and app token
- HTTPS connection
- OCS API enabled on Nextcloud

## Configuration

Set these environment variables:

```bash
export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_USER="your-username"
export NEXTCLOUD_TOKEN="your-app-token"
```

Or create `~/.config/nextcloud/config.json`:
```json
{
  "url": "https://cloud.example.com",
  "user": "your-username",
  "token": "your-app-token"
}
```

## Tool Reference

### `nextcloud-capabilities` - Get server capabilities

```bash
# Get all capabilities
nextcloud-capabilities

# Get specific capability section
nextcloud-capabilities --section core
nextcloud-capabilities --section theming
nextcloud-capabilities --section files
nextcloud-capabilities --section deck
```

### `nextcloud-version` - Get server version

```bash
# Get full version info
nextcloud-version

# Get version only
nextcloud-version --short
```

### `nextcloud-apps` - List installed apps

```bash
# List all apps
nextcloud-apps

# Filter by enabled state
nextcloud-apps --enabled

# Filter by name
nextcloud-apps --search calendar
```

### `nextcloud-theming` - Get theming information

```bash
# Get all theming data
nextcloud-theming

# Get color scheme only
nextcloud-theming --colors
```

### `nextcloud-quota` - Get user quota information

```bash
# Get quota (if files app provides)
nextcloud-quota
```

## API Details

### Capabilities Endpoint

**URL:** `{NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities`

**Method:** GET

**Headers:**
```
OCS-APIRequest: true
Accept: application/json
Authorization: Basic {base64(user:token)}
```

**Response Format:** OCS XML with JSON data inside:
```xml
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>200</statuscode>
    <message>OK</message>
  </meta>
  <data>
    <!-- JSON data here -->
  </data>
</ocs>
```

## Capability Sections

### Core Capabilities

```json
{
  "core": {
    "pollinterval": 60,
    "webdav-root": "remote.php/webdav",
    "referenceapi": "https://github.com/nextcloud/server"
  }
}
```

### Theming Capabilities

```json
{
  "theming": {
    "name": "Nextcloud",
    "url": "https://nextcloud.com",
    "slogan": "A safe home for all your data",
    "color": "#0082c9",
    "color-text": "#ffffff",
    "color-element": "#0082c9",
    "color-element-bright": "#aaaaaa",
    "color-element-dark": "#555555",
    "logo": "https://cloud.example.com/index.php/apps/theming/logo?v=1",
    "background": "https://cloud.example.com/index.php/apps/theming/background?v=1",
    "background-plain": "",
    "background-default": ""
  }
}
```

### Files Capabilities

```json
{
  "files": {
    "versioning": true,
    "bigfilechunking": true,
    "undelete": true,
    "blacklisted_files": "",
    "direct_download": true,
    "direct_editing": true,
    "sharing": {
      "api_enabled": true,
      "public": {
        "enabled": true,
        "password": {
          "enforced": false,
          "enforced_for": {}
        },
        "expire_date": {
          "enabled": true,
          "enforced": false,
          "days": ""
        },
        "multiple": true,
        "upload": false
      },
      "resharing": {
        "enabled": true,
        "upload": true
      }
    },
    "federated_cloud_sharing": {
      "incoming": true,
      "outgoing": false
    }
  }
}
```

### Deck Capabilities

```json
{
  "deck": {
    "enabled": true,
    "version": "1.0.0",
    "board_limits": [],
    "max_upload_size": 10485760
    "can_create_boards": true,
    "can_manage": true
    "file_attachments": true,
    "comments": true,
    "labels": true
    "archived_board_support": false
    "archived_cards_support": false,
    "card_attachments": true,
    "acl_support": true,
    "acl_shares": true,
    "default_permission": {
      "PERMISSION_READ": true,
      "PERMISSION_EDIT": true,
      "PERMISSION_MANAGE": false,
      "PERMISSION_SHARE": false
    },
    "calendar": false
    "notifications": true
    "polling_interval": 60
    "version_history": [
      {
        "version": "1.0.0",
        "features": "board_limits, card_attachments, comments, labels"
      }
    ]
  }
}
```

### Talk Capabilities

```json
{
  "spreed": {
    "enabled": true,
    "version": "19.0.0",
    "features": {
      "audio": true,
      "video": true,
      "chat": true,
      "guest-signaling": false,
      "rooms": {
        "allow_guests": false,
        "max_rooms": -1,
        "max_participants": -1
      },
      "recording": {
        "enabled": false,
        "group_only": false
      },
      "breakout_rooms": false,
      "webinar": false,
      "signaling": {
        "mode": "internal",
        "version": "2",
        "support": []
      }
    },
      "rich_object_list": true,
      "rich_object_config": false,
      "rich_object_list_share": true,
      "edit_messages": true,
      "federation": false,
      "voice": {
        "bridge": false
      },
      "notifications": {
        "version": "3",
        "notifications": true,
        "push": true,
        "sound": true
      },
      "expiration": {
        "enabled": false,
        "hours": ""
      },
      "circles": false,
      "mentions": false,
      "commands": false
    }
  }
}
```

### Notifications Capabilities

```json
{
  "notifications": {
    "ocs-endpoints": {
      "list": "/ocs/v2.php/apps/notifications/api/v2/notifications",
      "get": "/ocs/v2.php/apps/notifications/api/v2/notifications/{id}",
      "delete": "/ocs/v2.php/apps/notifications/api/v2/notifications/{id}",
      "push": "/ocs/v2.php/apps/notifications/api/v2/push",
      "devices": "/ocs/v2.php/apps/notifications/api/v2/devices",
      "register": "/ocs/v2.php/apps/notifications/api/v2/devices",
      "delete-device": "/ocs/v2.php/apps/notifications/api/v2/devices/{id}"
    },
    "features": {
      "notifications": true,
      "push": false,
      "sound": "",
      "admin-notifications": false
    }
  }
}
```

### Calendar Capabilities

```json
{
  "calendar": {
    "installed": true,
    "version": "4.0.0",
    "features": {
      "birthday-calendar": false,
      "publishing": false,
      "rich-description": false,
      "alarm": true,
      "timezones": true,
      "caldav": true,
      "sharee": {
        "api_enabled": true
      },
      "webcal": {
        "enabled": false
      }
    },
    "versionhistory": []
  }
}
```

### Contacts Capabilities

```json
{
  "dav": {
    "contacts": {
      "enabled": true,
      "version": "6.0.0",
      "features": {
        "photo": false,
        "circles": false,
        "addressbooks": true,
        "version": "6.0.0"
      }
    }
  }
}
```

### Notes Capabilities

```json
{
  "notes": {
    "installed": true,
    "version": "4.6.4",
    "features": {
      "version": "4.6.4",
      "api_version": "1.0",
      "files": false,
      "versioning": true,
      "markdown": false,
      "markdown_file_extension": "txt",
      "markdown_file_extension_is_customizable": false
      "description_max_length": null,
      "categories": false,
      "editable": true,
      "custom_properties": null
    }
  }
}
```

## Implementation Notes

### Authentication

```bash
curl -u ${NEXTCLOUD_USER}:${NEXTCLOUD_TOKEN} \
  -H "OCS-APIRequest: true" \
  -H "Accept: application/json" \
  ${NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities
```

### Example Request

```bash
curl -u ${USER}:${TOKEN} \
  -H "OCS-APIRequest: true" \
  -H "Accept: application/json" \
  https://cloud.example.com/ocs/v1.php/cloud/capabilities
```

### Example Response

```json
{
  "ocs": {
    "meta": {
      "statuscode": 100,
      "status": "ok"
    },
    "data": {
      "version": {
        "major": 25,
        "minor": 0,
        "micro": "2",
        "string": "25.0.2",
        "edition": "",
        "extendedSupport": ""
      },
      "capabilities": {
        "core": { ... },
        "theming": { ... },
        "files": { ... },
        "deck": { ... },
        "spreed": { ... },
        "notifications": { ... },
        "calendar": { ... },
        "dav": { ... },
        "notes": { ... }
      }
    }
  }
}
```

## Use Cases

### 1. Validate Server Capabilities

```bash
# Check if Deck is enabled
if nextcloud-capabilities | jq -r '.capabilities.deck.enabled'; then
  echo "Deck is available"
else
  echo "Deck not available"
fi

# Check Deck version
nextcloud-capabilities | jq -r '.capabilities.deck.version.string'
```

### 2. Check API Version

```bash
# Get version
VERSION=$(nextcloud-version | jq -r '.capabilities.version.string')

# Check if minimum version is met
if [ "$VERSION" \> "25.0.0" ]; then
  echo "Server meets minimum version requirement"
else
  echo "Server too old"
fi
```

### 3. Validate Feature Support

```bash
# Check if notifications push is enabled
if nextcloud-capabilities | jq -r '.capabilities.notifications.features.push'; then
  echo "Push notifications supported"
else
  echo "Push notifications not supported"
fi

# Check if direct download is available
if nextcloud-capabilities | jq -r '.capabilities.files.sharing.direct_download'; then
  echo "Direct download feature available"
else
  echo "Direct download not available"
fi
```

### 4. Get Theming Colors

```bash
# Get color scheme
nextcloud-theming

# Parse colors (example output)
COLOR=$(echo "$THEMING" | jq -r '.theming.color')
TEXT_COLOR=$(echo "$THEMING" | jq -r '.theming.color_text')

echo "Primary color: $COLOR"
echo "Text color: $TEXT_COLOR"
```

### 5. App Availability Check

```bash
# Check which apps are installed
APPS=$(nextcloud-apps)

echo "Installed apps:"
echo "$APPS" | jq -r '.data.capabilities | keys'

# Check if specific app exists
if echo "$APPS" | jq -r 'has("deck")'; then
  echo "Deck is installed"
fi

if echo "$APPS" | jq -r 'has("calendar")'; then
  echo "Calendar is installed"
fi

if echo "$APPS" | jq -r 'has("notes")'; then
  echo "Notes is installed"
fi
```

## Error Handling

| HTTP Status | Meaning | Action |
|-------------|---------|--------|
| 200 | Success | Parse capabilities XML/JSON |
| 401 | Unauthorized | Check credentials |
| 403 | Forbidden | Check permissions |
| 404 | Not Found | API endpoint not available |
| 500 | Server Error | Nextcloud server error |

## Testing

```bash
# Test connection
nextcloud-test --capabilities

# Test capabilities retrieval
nextcloud-test --capabilities-get

# Test specific section
nextcloud-test --capabilities --section deck

# Test all sections
nextcloud-test --capabilities --all
```

## Dependencies

- `curl` for HTTP requests
- `jq` for JSON parsing (recommended)

## Best Practices

1. **Cache capabilities** - Capabilities rarely change, cache for 5-10 minutes
2. **Validate before use** - Check if app is enabled before using app-specific APIs
3. **Version compatibility** - Check server version before using features
4. **Handle errors gracefully** - If capabilities endpoint returns error, assume minimal feature set
5. **Theming** - Use theming colors to customize UI when applicable
6. **Group Limits** - Check group_limit in Deck capabilities before creating boards

## Future Enhancements

- [ ] Capabilities change detection
- [ ] App installation/removal tracking
- [ ] Feature compatibility matrix
- [ ] Automatic API version adaptation
- [ ] Server health check integration

## Related Skills

- **nextcloud-files** - For file operations (capabilities will inform approach)
- **nextcloud-deck** - For Kanban boards (check Deck capabilities first)
- **nextcloud-talk** - For chat/calls (check Talk capabilities first)
- **nextcloud-calendar** - For calendar events (check Calendar capabilities first)
- **nextcloud-notes** - For notes (check Notes capabilities first)

---

*OCS API implementation for Nextcloud capabilities detection*