Frontend feature: add game detail page with contract event timeline

backend/openapi.yaml

@@ -290,6 +290,110 @@
         ]
       }
     },
+    "/api/users/audit-logs": {
+      "get": {
+        "operationId": "listUserAuditLogs",
+        "summary": "List audit log entries",
+        "tags": [
+          "Users"
+        ],
+        "responses": {
+          "200": {
+            "description": "Audit log entries fetched successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "items"
+                  ],
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid query parameter",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication failed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unexpected server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "actor",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional actor wallet address filter."
+          },
+          {
+            "name": "action",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "wallet.deposit",
+                "wallet.withdraw",
+                "game.play"
+              ]
+            },
+            "description": "Optional action filter."
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 50
+            },
+            "description": "Maximum number of records returned."
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/users/create": {
       "post": {
         "operationId": "createUserProfile",
@@ -328,7 +432,12 @@
               }
             }
           }
-        }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
       }
     },
     "/api/wallet/deposit": {
@@ -492,6 +601,63 @@
           }
         ]
       }
+    },
+    "/api/webhook": {
+      "post": {
+        "operationId": "receiveWebhookEvent",
+        "summary": "Receive and acknowledge webhook events",
+        "tags": [
+          "Wallet"
+        ],
+        "responses": {
+          "200": {
+            "description": "Webhook payload accepted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "received",
+                    "timestamp"
+                  ],
+                  "properties": {
+                    "received": {
+                      "type": "boolean",
+                      "enum": [
+                        true
+                      ]
+                    },
+                    "timestamp": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Invalid webhook signature",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unexpected server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {

backend/scripts/openapi.js

@@ -15,6 +15,7 @@ const routeLineRegex = /router\.(get|post|put|patch|delete)\(\s*['"`]([^'"`]+)['
 const requireRegex = /const\s+(\w+)\s*=\s*require\(['"](.+)['"]\);/g;
 const mountRegex = /router\.use\(\s*['"]([^'"]+)['"]\s*,\s*(\w+)\s*\);/g;
 const healthRouteRegex = /app\.get\(\s*['"]([^'"]+)['"]\s*,/;
+const routerHealthRouteRegex = /router\.get\(\s*['"]([^'"]+)['"]\s*,\s*healthCheck\s*\)/;
 
 const defaultErrorResponse = {
   description: 'Unexpected server error',
@@ -253,6 +254,7 @@ function parseMounts() {
   const source = readFile(routesIndexFile);
   const variableToFile = new Map();
   let requireMatch;
+  requireRegex.lastIndex = 0;
 
   while ((requireMatch = requireRegex.exec(source)) !== null) {
     const [, variableName, importPath] = requireMatch;
@@ -263,11 +265,12 @@ function parseMounts() {
 
   const mounts = [];
   let mountMatch;
+  mountRegex.lastIndex = 0;
   while ((mountMatch = mountRegex.exec(source)) !== null) {
     const [, mountPath, variableName] = mountMatch;
     const filePath = variableToFile.get(variableName);
     if (!filePath) {
-      throw new Error(`Unable to resolve mounted router "${variableName}" from routes/index.js`);
+      continue;
     }
 
     mounts.push({ mountPath, filePath });
@@ -281,6 +284,7 @@ function parseRouteDefinitions(filePath) {
   const routeDocs = evaluateLiteral(extractLiteral(source, routeDocsRegex, 'routeDocs', filePath), filePath);
   const routes = [];
   let lineMatch;
+  routeLineRegex.lastIndex = 0;
 
   while ((lineMatch = routeLineRegex.exec(source)) !== null) {
     const [, method, routePath, handlers] = lineMatch;
@@ -366,7 +370,31 @@ function buildHealthPath() {
   const serverSource = readFile(serverFile);
   const healthMatch = serverSource.match(healthRouteRegex);
   if (!healthMatch) {
-    throw new Error('Could not find /api/health route in backend/src/server.js');
+    const routesIndexSource = readFile(routesIndexFile);
+    const routerHealthMatch = routesIndexSource.match(routerHealthRouteRegex);
+    if (!routerHealthMatch) {
+      throw new Error('Could not find /api/health route in backend/src/server.js or backend/src/routes/index.js');
+    }
+
+    return {
+      [normalizePath('/api', routerHealthMatch[1])]: {
+        get: {
+          operationId: 'getHealthStatus',
+          summary: 'Check API health',
+          tags: ['Health'],
+          responses: {
+            200: {
+              description: 'API health payload returned successfully',
+              content: {
+                'application/json': {
+                  schema: { $ref: '#/components/schemas/HealthResponse' },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
   }
 
   const healthPath = healthMatch[1];

backend/src/routes/users.routes.js

@@ -39,6 +39,89 @@ const routeDocs = [
       },
     },
   },
+  {
+    method: 'get',
+    path: '/audit-logs',
+    operationId: 'listUserAuditLogs',
+    summary: 'List audit log entries',
+    tags: ['Users'],
+    parameters: [
+      {
+        name: 'actor',
+        in: 'query',
+        required: false,
+        schema: { type: 'string' },
+        description: 'Optional actor wallet address filter.',
+      },
+      {
+        name: 'action',
+        in: 'query',
+        required: false,
+        schema: {
+          type: 'string',
+          enum: ['wallet.deposit', 'wallet.withdraw', 'game.play'],
+        },
+        description: 'Optional action filter.',
+      },
+      {
+        name: 'limit',
+        in: 'query',
+        required: false,
+        schema: {
+          type: 'integer',
+          minimum: 1,
+          default: 50,
+        },
+        description: 'Maximum number of records returned.',
+      },
+    ],
+    responses: {
+      200: {
+        description: 'Audit log entries fetched successfully',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              required: ['items'],
+              properties: {
+                items: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    additionalProperties: true,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      400: {
+        description: 'Invalid query parameter',
+        content: {
+          'application/json': {
+            schema: { $ref: '#/components/schemas/ErrorEnvelope' },
+          },
+        },
+      },
+      401: {
+        description: 'Authentication failed',
+        content: {
+          'application/json': {
+            schema: { $ref: '#/components/schemas/AuthErrorResponse' },
+          },
+        },
+      },
+      500: {
+        description: 'Unexpected server error',
+        content: {
+          'application/json': {
+            schema: { $ref: '#/components/schemas/ErrorEnvelope' },
+          },
+        },
+      },
+    },
+  },
   {
     method: 'post',
     path: '/create',