Add extensible reason code handling for capacity check API responses

[Copilot]

The capacity check API now returns a reason field in denial responses (e.g., {"allowed": false, "reason": "outofdate"}). This implements handling for these reason codes with user-facing error messages.

Changes

• Added REASON_MESSAGES mapping for extensible reason-to-message translation

  • Currently defines outofdate: "App out of date, please update"
  • Future reasons added by extending this mapping only

• Enhanced checkCapacity() to parse and store API reason codes

  • Falls back to "capacity_full" when no reason provided (backward compatible)
  • Debug logs include reason field: [CAPACITY] API returned reason code: outofdate

• Updated disconnect event handler to prioritize REASON_MESSAGES lookup

  • Checks mapping first, then falls through to hardcoded cases
  • Unknown reasons show: "Connection not allowed: [reason]" with raw code
  • Maintains all existing disconnect reason behaviors

• Documentation updates in STATUS_MESSAGES.md and CONNECTION_WORKFLOW.md

Example

const REASON_MESSAGES = {
  outofdate: "App out of date, please update",
  maintenance: "Service under maintenance",  // Future addition
};

// API response: {"allowed": false, "reason": "outofdate"}
// → User sees: "App out of date, please update"

// API response: {"allowed": false, "reason": "new_reason"}  
// → User sees: "Connection not allowed: new_reason"

// API response: {"allowed": false}  
// → User sees: "WarDriving app has reached capacity" (legacy)

Adding new reason codes requires only updating the REASON_MESSAGES constant.

Original prompt

MeshCore GOME WarDriver - Development Guidelines

Overview

This document defines the coding standards and requirements for all changes to the MeshCore GOME WarDriver repository. AI agents and contributors must follow these guidelines for every modification.

---

Code Style & Standards

Debug Logging

• ALWAYS include debug console logging for significant operations
• Use the existing debug helper functions:
  • debugLog(message, ...args) - For general debug information
  • debugWarn(message, ... args) - For warning conditions
  • debugError(message, ... args) - For error conditions
• Debug logging is controlled by the DEBUG_ENABLED flag (URL parameter ? debug=true)
• Log at key points: function entry, API calls, state changes, errors, and decision branches

Debug Log Tagging Convention

All debug log messages MUST include a descriptive tag in square brackets immediately after [DEBUG] that identifies the subsystem or feature area. This enables easier filtering and understanding of debug output.

Format: [DEBUG] [TAG] Message here

Required Tags:

Tag	Description
[BLE]	Bluetooth connection and device communication
[GPS]	GPS/geolocation operations
[PING]	Ping sending and validation
[API QUEUE]	API batch queue operations
[RX BATCH]	RX batch buffer operations
[PASSIVE RX]	Passive RX logging logic
[PASSIVE RX UI]	Passive RX UI rendering
[SESSION LOG]	Session log tracking
[UNIFIED RX]	Unified RX handler
[DECRYPT]	Message decryption
[UI]	General UI updates (status bar, buttons, etc.)
[CHANNEL]	Channel setup and management
[TIMER]	Timer and countdown operations
[WAKE LOCK]	Wake lock acquisition/release
[GEOFENCE]	Geofence and distance validation
[CAPACITY]	Capacity check API calls
[AUTO]	Auto ping mode operations
[INIT]	Initialization and setup
[ERROR LOG]	Error log UI operations

Examples:

// ✅ Correct - includes tag
debugLog("[BLE] Connection established");
debugLog("[GPS] Fresh position acquired: lat=45.12345, lon=-75.12345");
debugLog("[PING] Sending ping to channel 2");

// ❌ Incorrect - missing tag
debugLog("Connection established");
debugLog("Fresh position acquired");

Status Messages

• ALWAYS update STATUS_MESSAGES.md when adding or modifying user-facing status messages
• Use the setStatus(message, color) function for all UI status updates
• Use appropriate STATUS_COLORS constants:
  • STATUS_COLORS.idle - Default/waiting state
  • STATUS_COLORS. success - Successful operations
  • STATUS_COLORS.warning - Warning conditions
  • STATUS_COLORS.error - Error states
  • STATUS_COLORS.info - Informational/in-progress states

---

Documentation Requirements

Code Comments

• Document complex logic with inline comments
• Use JSDoc-style comments for functions:
  • @param for parameters
  • @returns for return values
  • Brief description of purpose

docs/STATUS_MESSAGES.md Updates

When adding new status messages, include:

• The exact status message text
• When it appears (trigger condition)
• The status color used
• Any follow-up actions or states���

docs/CONNECTION_WORKFLOW.md Updates

When modifying connect or disconnect logic, you must:

• Read docs/CONNECTION_WORKFLOW.md before making the change (to understand current intended behavior).
• Update docs/CONNECTION_WORKFLOW.md so it remains accurate after the change:
  • Steps/sequence of the workflow
  • Any new states, retries, timeouts, or error handling
  • Any UI impacts (buttons, indicators, status messages)

docs/PING_AUTO_PING_WORKFLOW.md Updates

When modifying ping or auto-ping logic, you must:

• Read docs/PING_AUTO_PING_WORKFLOW.md before making the change (to understand current intended behavior).
• Update docs/PING_AUTO_PING_WORKFLOW.md so it remains accurate after the change:
  • Ping flows (manual sendPing(), auto-ping lifecycle)
  • Validation logic (geofence, distance, cooldown)
  • GPS acquisition and payload construction
  • Repeater tracking and MeshMapper API posting
  • Control locking and cooldown management
  • Auto mode behavior (intervals, wake lock, page visibility)
  • Any UI impacts (buttons, status messages, countdown displays)

---

Requested Change

Handling Capacity Check API Responses for Device Connection

When connecting to a device, the current workflow is to POST to the Capacity Check API. The response indicates whether the connection is allowed via the allowed boolean field, e.g.:

{ "allowed": true }

or

{ "allowed": false }

New Behavior: Adding Reason Codes

The API now supports a reason field in its response, for example:

{ "allowed": false, "reason": "outofdate" }

Requirements for Handling the Response

• If the reason field exists in the respo...

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.