feat(api): create ResponseHelper for standardized success responses

Introduces a new `ResponseHelper` class with a static `success` method.
This helper centralizes the logic for creating standardized `SuccessApiResponse`
objects, automatically populating metadata like the request ID and timestamp,
and serializing the final payload into a `Response.json` object.

This refactoring prepares the ground for simplifying the response-building
logic in various route handlers, reducing boilerplate code and improving
maintainability.

Author: fulleni

lib/src/helpers/response_helper.dart

@@ -0,0 +1,43 @@
+import 'dart:io';
+
+import 'package:dart_frog/dart_frog.dart';
+import 'package:ht_shared/ht_shared.dart';
+
+import '../../routes/_middleware.dart';
+
+/// A utility class to simplify the creation of standardized API responses.
+abstract final class ResponseHelper {
+  /// Creates a standardized success JSON response.
+  ///
+  /// This helper encapsulates the boilerplate of creating metadata, wrapping the
+  /// payload in a [SuccessApiResponse], and serializing it to JSON.
+  ///
+  /// - [context]: The request context, used to read the `RequestId`.
+  /// - [data]: The payload to be included in the response.
+  /// - [toJsonT]: A function that knows how to serialize the [data] payload.
+  ///   This is necessary because of Dart's generics. For a simple object, this
+  ///   would be `(data) => data.toJson()`. For a paginated list, it would be
+  ///   `(paginated) => paginated.toJson((item) => item.toJson())`.
+  /// - [statusCode]: The HTTP status code for the response. Defaults to 200 OK.
+  static Response success<T>({
+    required RequestContext context,
+    required T data,
+    required Map<String, dynamic> Function(T data) toJsonT,
+    int statusCode = HttpStatus.ok,
+  }) {
+    final metadata = ResponseMetadata(
+      requestId: context.read<RequestId>().id,
+      timestamp: DateTime.now().toUtc(),
+    );
+
+    final responsePayload = SuccessApiResponse<T>(
+      data: data,
+      metadata: metadata,
+    );
+
+    return Response.json(
+      statusCode: statusCode,
+      body: responsePayload.toJson(toJsonT),
+    );
+  }
+}