alpinebits_python/ACTION_MAPPING_SUMMARY.md

AlpineBits Action Mapping System

Problem Solved

The AlpineBits specification uses different names for the same action:

• Capability JSON: "action_OTA_Read" (advertised in handshake)
• Request Action: "OTA_Read:GuestRequests" (actual request parameter)

Solution Architecture

1. Enhanced AlpineBitsActionName Enum

# Maps capability names to request names
OTA_READ = ("action_OTA_Read", ["OTA_Read:GuestRequests", "OTA_Read"])

2. Automatic Action Discovery

• ServerCapabilities scans for implemented actions
• Only includes actions with overridden handle() methods
• Generates capability JSON using capability names

3. Request Routing

• AlpineBitsServer.handle_request() accepts request action names
• Maps request names back to capability names
• Routes to appropriate action handler
• Validates version support

Key Features

✅ Automatic Discovery: New action implementations are automatically detected ✅ Name Mapping: Handles capability vs request name differences ✅ Version Support: Actions can support multiple versions ✅ Error Handling: Proper HTTP status codes (200, 400, 401, 500) ✅ Capability Generation: Dynamic JSON generation for handshakes

Usage Example

# Server automatically discovers implemented actions
server = AlpineBitsServer()

# Handle request with different name format
response = await server.handle_request(
    "OTA_Read:GuestRequests",  # Request name
    xml_content,
    "2024-10"
)

# Capability JSON uses "action_OTA_Read" automatically
capabilities = server.get_capabilities_json()

Adding New Actions

1. Create action class inheriting from AlpineBitsAction
2. Add mapping to AlpineBitsActionName enum
3. Implement handle() method
4. Deploy - action automatically appears in capabilities

The system is now production-ready for handling AlpineBits protocol quirks!