// Version: 2.0.0 | Created: 2026-04-02 | Updated: 2026-04-11
// Synchronous MXC URI to HTTP URL resolution.
//
// Synapse 1.120+ requires authenticated media downloads. The old
// /_matrix/media/v3/download/ endpoint is frozen and returns 404.
// We use /_matrix/client/v1/media/download/ with the access token.

import 'package:matrix/matrix.dart';

/// Resolves an `mxc://` [Uri] to an authenticated HTTP download URL.
/// Returns `null` if the URI is not mxc:// or the client is not connected.
String? resolveMxcUrl(Client client, Uri? mxcUri) {
  if (mxcUri == null || !mxcUri.isScheme('mxc')) return null;
  final homeserver = client.homeserver;
  if (homeserver == null) return null;

  final serverName = mxcUri.host;
  final port = mxcUri.hasPort ? ':${mxcUri.port}' : '';
  final mediaId = mxcUri.path; // includes leading /

  // Use the authenticated media endpoint (MSC3916).
  final base = homeserver
      .resolve('_matrix/client/v1/media/download/$serverName$port$mediaId')
      .toString();

  // Append the access token so CachedNetworkImage / Image.network can
  // fetch without custom headers. The token is already in the browser's
  // JS memory so this doesn't expand the attack surface.
  final token = client.accessToken;
  if (token == null) return base;
  return '$base?access_token=$token';
}