Enhancement: Add hexadecimal channel hashes to the analytics API and use typed response structs #193

Summary

Follow-up to #190 and PR #192.

The /api/analytics/channels endpoint currently returns channel hashes as decimal strings (e.g. "17"), requiring frontend consumers to convert them into hexadecimal for display.

PR #192 addresses this in the Analytics → Channels UI by converting decimal-string hashes to hexadecimal and fixing numeric sorting. However, the underlying API representation remains unchanged.

This enhancement should expose a consistent hexadecimal representation from the backend, improve the response's type safety, and reduce duplicated conversion logic across clients.

Proposed changes

1. Add a hexadecimal hash field to the API response

Add a hashHex field alongside the existing hash field in each channel analytics record.

Example:

{
  "hash": "17",
  "hashHex": "0x11",
  "name": "Public",
  "messages": 3,
  "senders": 1,
  "lastActivity": "...",
  "encrypted": false
}

Requirements:

• Preserve the existing hash field and its decimal-string format for backward compatibility.
• Represent valid numeric channel hash bytes as uppercase hexadecimal, prefixed with 0x and zero-padded to two digits.
• Handle nonnumeric or special channel identifiers without introducing invalid conversions.
• Keep existing channel navigation and deep links functional.

2. Replace untyped response maps with named Go structs

Refactor the channels analytics response construction to use named structs instead of map[string]interface{} for response records.

This aligns with the repository's AGENTS.md guidance to reduce untyped map usage.

Ensure the refactor preserves existing JSON field names, response structure, filtering behavior, and analytics calculations.

3. Reconcile API contracts and documentation

Review and update:

• docs/api-spec.md, which currently documents hash as a string.
• proto/analytics.proto, where ChannelAnalyticsSummary.hash is currently declared as int32.
• Existing backend tests that expect decimal-string hashes.

Document the intended wire format and add the hexadecimal field to the applicable schema without introducing breaking changes.

4. Review other channel hash consumers

Check whether public/channels.js or other API consumers independently convert or display channel hashes.

Where appropriate, use the backend-provided hashHex for display while retaining the original hash identifier for navigation, filtering, and existing bookmarks.

Acceptance criteria

• /api/analytics/channels provides hashHex for valid numeric channel hashes.
• Hash 17 renders as 0x11, 129 as 0x81, and 5 as 0x05.
• The existing hash field remains backward compatible.
• Nonnumeric or special identifiers are handled safely and consistently.
• Channel analytics response records use named Go structs instead of untyped maps.
• Existing analytics aggregation and filtering behavior is preserved.
• API documentation and protocol definitions are consistent with the implemented contract.
• Backend tests cover hexadecimal formatting, response serialization, and compatibility.
• Frontend consumers are reviewed for duplicate conversions or inconsistent hash display.
• Existing channel deep links continue to work.
• Relevant Go and frontend regression tests pass.

Related issues and PRs

• Original bug: Channel hashes in Channel Analytics are being displayed as a decimal value rather than hexadecimal #190
• Frontend fix: fix(analytics): convert decimal channel hashes to hex format in UI #192
• Requested as a follow-up in the PR fix(analytics): convert decimal channel hashes to hex format in UI #192 review discussion.

Scope

This is a backend API enhancement with limited frontend integration as needed.

It should not change channel hash calculation, MeshCore protocol behavior, or the existing meaning of channel identifiers.