# Entropia Nexus API Documentation Summary

> Summary of completed Nexus API documentation and implementation for EU-Utility
> 
> **Date:** 2025-02-13

---

## Files Created/Updated

### Documentation Files Created

| File | Description | Size |
|------|-------------|------|
| `docs/NEXUS_LINKTREE.md` | Complete URL reference for all Nexus endpoints | ~7.5 KB |
| `docs/NEXUS_API_REFERENCE.md` | Full technical API documentation | ~18 KB |
| `docs/NEXUS_USAGE_EXAMPLES.md` | Plugin developer examples | ~18 KB |

### Code Files Updated

| File | Changes |
|------|---------|
| `core/nexus_api.py` | Added all 25+ entity types, `search_by_type()`, `get_entity_details()` |
| `core/plugin_api.py` | Added `nexus_search()`, `nexus_get_item_details()`, `nexus_get_market_data()` |
| `plugins/base_plugin.py` | Added convenience methods for plugins to access Nexus API |

---

## What's Documented

### 1. LinkTree (NEXUS_LINKTREE.md)

Complete reference of all Nexus URLs:

- **Base URLs**: `api.entropianexus.com` vs `www.entropianexus.com`
- **API Endpoints**: All 25+ entity endpoints
- **Web Pages**: Browseable web interface URLs
- **Entity Type Mapping**: API endpoint → web path conversions
- **Query Parameters**: All available search/filter parameters
- **Rate Limits**: Request limits by endpoint type
- **Response Formats**: JSON structure examples

### 2. API Reference (NEXUS_API_REFERENCE.md)

Complete technical documentation:

- **Authentication**: Public API (no auth required)
- **Base Configuration**: Rate limits, retry settings, cache TTL
- **Entity Types**: All 25+ types documented with descriptions
- **Endpoints**: 
  - `/search` - Universal search
  - `/{entity-type}` - Entity-specific search
  - `/items/{id}` - Item details
  - `/items/{id}/market` - Market data
- **Request Parameters**: Query options, filters, pagination
- **Response Formats**: Complete field documentation for each entity type
- **Error Handling**: HTTP codes, exceptions, error responses
- **Rate Limits**: Limits per endpoint type
- **Field Name Conventions**: Documentation of snake_case vs PascalCase issue
- **Data Classes**: Python dataclass reference

### 3. Usage Examples (NEXUS_USAGE_EXAMPLES.md)

Practical examples for plugin developers:

- **Basic Search**: Simple queries with limits
- **Entity-Specific Searches**: Weapons, mobs, blueprints, locations, skills
- **Item Details**: Full item analysis patterns
- **Market Data**: Price checking, monitoring, comparisons
- **Complete Plugin Examples**:
  - Weapon Comparator (with DPP calculation)
  - Mob Info lookup
  - Price Checker
- **Advanced Patterns**: Caching, batch processing, error handling

---

## Implementation Status

### Entity Types Supported

All 25+ entity types are now supported:

#### Equipment & Items
- ✅ `items` - General items
- ✅ `weapons` - Weapons
- ✅ `armors` - Armors
- ✅ `enhancers` - Enhancers

#### Tools & Professional
- ✅ `medicaltools` - Medical tools
- ✅ `finders` - Mining finders
- ✅ `excavators` - Excavators
- ✅ `refiners` - Refiners

#### Crafting & Materials
- ✅ `blueprints` - Blueprints
- ✅ `materials` - Materials

#### Creatures
- ✅ `mobs` - Creatures
- ✅ `pets` - Pets

#### Locations
- ✅ `locations` - Locations
- ✅ `teleporters` - Teleporters
- ✅ `shops` - Shops
- ✅ `vendors` - Vendors
- ✅ `planets` - Planets
- ✅ `areas` - Areas

#### Other
- ✅ `skills` - Skills
- ✅ `vehicles` - Vehicles
- ✅ `decorations` - Decorations
- ✅ `furniture` - Furniture
- ✅ `storagecontainers` - Storage
- ✅ `strongboxes` - Strongboxes

### API Methods Available to Plugins

Plugins can now access the Nexus API through:

```python
# In any plugin (extends BasePlugin)
class MyPlugin(BasePlugin):
    def search(self):
        # Search for any entity type
        results = self.nexus_search("ArMatrix", entity_type="weapons")
        
        # Get item details
        details = self.nexus_get_item_details("armatrix_lp-35")
        
        # Get market data
        market = self.nexus_get_market_data("armatrix_lp-35")
        
        # Check API availability
        if self.nexus_is_available():
            # Safe to make calls
            pass
```

### Core API Methods (nexus_api.py)

```python
from core.nexus_api import get_nexus_api

api = get_nexus_api()

# Search methods
api.search_items(query, limit=20)
api.search_mobs(query, limit=20)
api.search_all(query, limit=20)
api.search_by_type(query, entity_type="weapons", limit=20)

# Detail methods
api.get_item_details(item_id)
api.get_entity_details(entity_id, entity_type="mobs")
api.get_market_data(item_id)

# Batch methods
api.get_items_batch([item_id1, item_id2])
api.get_market_batch([item_id1, item_id2])

# Utility
api.clear_cache()
api.is_available()
```

---

## Known Field Name Conventions

**Important**: The API returns field names in inconsistent formats:

| Concept | May Appear As |
|---------|---------------|
| ID | `id` or `Id` |
| Name | `name` or `Name` |
| TT Value | `tt_value`, `TTValue`, `TtValue` |
| Damage | `damage` or `Damage` |

**Solution**: The implementation handles both formats:

```python
# Safe field access
name = item.get('name') or item.get('Name')
tt_value = item.get('tt_value') or item.get('TTValue')
```

---

## Rate Limits

| Endpoint Type | Limit |
|---------------|-------|
| General API | 5 req/sec |
| Search | 10 req/min |
| Market Data | 60 req/min |
| Item Details | 30 req/min |

**Implementation**: The client automatically handles:
- Rate limiting (0.2s between requests)
- Retry with exponential backoff (max 3 retries)
- 5-minute default cache for responses

---

## Testing

The implementation includes a test file:

```bash
cd projects/EU-Utility
python tests/test_nexus_api.py
```

Tests verify:
- Singleton pattern
- PluginAPI integration
- All method availability
- Configuration values

---

## Usage for Plugin Developers

### Basic Plugin Template

```python
from plugins.base_plugin import BasePlugin

class MyPlugin(BasePlugin):
    name = "My Plugin"
    version = "1.0.0"
    
    def find_items(self, query):
        # Search Nexus
        results = self.nexus_search(query, entity_type="items")
        return results
    
    def analyze_item(self, item_id):
        # Get full details
        details = self.nexus_get_item_details(item_id)
        market = self.nexus_get_market_data(item_id)
        
        return {
            'item': details,
            'market': market
        }
```

### Entity Type Quick Reference

```python
# Valid entity_type values for nexus_search()
entity_types = [
    "items", "weapons", "armors",
    "mobs", "pets",
    "blueprints", "materials",
    "locations", "teleporters", "shops", "vendors", "planets", "areas",
    "skills",
    "enhancers", "medicaltools", "finders", "excavators", "refiners",
    "vehicles", "decorations", "furniture",
    "storagecontainers", "strongboxes"
]
```

---

## Related Files

| Path | Description |
|------|-------------|
| `core/nexus_api.py` | Core API client implementation |
| `core/plugin_api.py` | Plugin API with Nexus integration |
| `plugins/base_plugin.py` | Base plugin with Nexus convenience methods |
| `plugins/universal_search/plugin.py` | Real-world usage example |
| `plugins/nexus_search/plugin.py` | Alternative API client example |
| `tests/test_nexus_api.py` | Integration tests |

---

## Future Enhancements (Noted but Not Implemented)

These are documented but may require API support:

1. **Advanced Filtering**: `min_level`, `max_level`, `planet` parameters
2. **Pagination**: `offset` parameter for large result sets
3. **Bulk Endpoints**: Batch entity retrieval
4. **Real-time Data**: WebSocket support for live market data
5. **User Authentication**: If private endpoints become available

---

## Summary

✅ **Complete documentation** for all Nexus endpoints  
✅ **25+ entity types** fully supported  
✅ **Plugin integration** via PluginAPI and BasePlugin  
✅ **Usage examples** for common patterns  
✅ **Error handling** and rate limiting implemented  
✅ **Field name handling** for API inconsistencies  

The implementation is ready for plugin developers to use the Entropia Nexus API.