Merge pull request #99 from johnsmccain/main

feat: add timestamp header helper for public creator responses

Author: Chucks1093

prisma/schema/schema.prisma

@@ -5,8 +5,9 @@
 // Try Prisma Accelerate: https://pris.ly/cli/accelerate-init
 
 generator client {
-  provider = "prisma-client-js"
-  output   = "../../node_modules/.prisma/client"
+  provider        = "prisma-client-js"
+  output          = "../../node_modules/.prisma/client"
+  previewFeatures = ["prismaSchemaFolder"]
 }
 
 datasource db {

src/modules/creator/creator.controller.ts

@@ -8,8 +8,7 @@ import {
   sendValidationError,
   ErrorCode,
 } from '../../utils/api-response.utils';
-
-// Creator service and utilities
+import { attachTimestampHeader } from '../../utils/timestamp-headers.utils';
 import { getPaginatedCreators } from './creator.service';
 import { parseCreatorSortOptions } from './creator.utils';
 import { parsePublicQuery } from '../../utils/public-query-parse.utils';
@@ -109,7 +108,7 @@ export const listCreators: RequestHandler = async (req, res) => {
     });
 
     const response = wrapPublicCreatorListResponse(creators, meta);
-
+    attachTimestampHeader(res);
     const filteredItems = Array.isArray(response.items)
       ? response.items.map((item) =>
           pickFields(item as Record<string, unknown>, selectedFields)
@@ -129,4 +128,4 @@ export const listCreators: RequestHandler = async (req, res) => {
     console.error('Error listing creators:', error);
     return sendError(res, 500, ErrorCode.INTERNAL_ERROR, 'Failed to retrieve creators');
   }
-};
+};

src/modules/creators/creators.controllers.ts

@@ -10,6 +10,7 @@ import {
    sendSuccess,
    sendValidationError,
 } from '../../utils/api-response.utils';
+import { attachTimestampHeader } from '../../utils/timestamp-headers.utils';
 import { parsePublicQuery } from '../../utils/public-query-parse.utils';
 import { buildOffsetPaginationMeta } from '../../utils/pagination.utils';
 import { buildCreatorListRequestContext } from './creator-list-context.utils';
@@ -43,6 +44,7 @@ export const httpListCreators: AsyncController = async (req, res, next) => {
          })
       );
 
+      attachTimestampHeader(res);
       sendSuccess(res, response);
    } catch (error) {
       next(error);
@@ -78,6 +80,7 @@ export const httpGetCreatorStats: AsyncController = async (req, res, next) => {
       // Serialize using the public stats mapper
       const stats = mapPublicCreatorStats(placeholderMetrics);
 
+      attachTimestampHeader(res);
       sendSuccess(res, stats);
    } catch (error) {
       next(error);

src/utils/timestamp-headers.utils.ts

@@ -0,0 +1,39 @@
+// src/utils/timestamp-headers.utils.ts
+// Centralizes timestamp header formatting for public creator-facing responses.
+
+import { Response } from 'express';
+
+/**
+ * Header name used to communicate the server-side response timestamp to clients.
+ *
+ * Clients can use this to detect stale cached responses or correlate
+ * request timing without parsing the response body.
+ */
+export const RESPONSE_TIMESTAMP_HEADER = 'X-Response-Timestamp';
+
+/**
+ * Formats a Date as an ISO 8601 string suitable for use in HTTP headers.
+ *
+ * @param date - Defaults to `new Date()` (now)
+ * @returns ISO 8601 UTC string, e.g. "2026-03-29T12:00:00.000Z"
+ */
+export function formatTimestampHeader(date: Date = new Date()): string {
+   return date.toISOString();
+}
+
+/**
+ * Attaches an `X-Response-Timestamp` header to the response.
+ *
+ * Call this before sending any public creator response so clients
+ * receive a consistent, parseable timestamp on every reply.
+ *
+ * @param res - Express response object
+ * @param date - Timestamp to attach; defaults to now
+ *
+ * @example
+ * attachTimestampHeader(res);
+ * sendSuccess(res, data);
+ */
+export function attachTimestampHeader(res: Response, date: Date = new Date()): void {
+   res.set(RESPONSE_TIMESTAMP_HEADER, formatTimestampHeader(date));
+}