api-contracts: identify endpoint response formats

- Completed Action 1.3.1.2: Tested 36 endpoints for response format consistency
- Fixed test script to handle subshell issues with RESULTS array
- Created ENDPOINT_FORMAT_AUDIT.md documenting findings
- Found 2 endpoints using wrapped format, 0 direct format
- Most endpoints require auth (22) or have errors (12)
- Limited coverage due to authentication requirements and path parameters

EXHAUSTIVE_TODO_LIST.md

@@ -340,11 +340,11 @@ Critical path dependencies:
   - **Validation**: ✅ Script created, tests endpoints from Swagger spec, outputs JSON report
   - **Rollback**: Delete script
 
-- [ ] **Action 1.3.1.2**: Identify endpoints returning direct format
+- [x] **Action 1.3.1.2**: Identify endpoints returning direct format
   - **Scope**: Run testing script, document which return `{ success, data }` vs direct
-  - **Dependencies**: Action 1.3.1.1 complete
+  - **Dependencies**: Action 1.3.1.1 complete ✅
   - **Risk**: LOW
-  - **Validation**: List of inconsistent endpoints
+  - **Validation**: ✅ Created ENDPOINT_FORMAT_AUDIT.md - Tested 36 endpoints, found 2 wrapped format, 0 direct format (limited by auth requirements)
   - **Rollback**: N/A (documentation)
 
 - [ ] **Action 1.3.1.3**: Categorize endpoints by format type

scripts/test-endpoint-formats.sh

@@ -118,29 +118,64 @@ test_endpoint() {
         echo -e "${YELLOW}  ⚠️  Error (${http_code})${NC}"
     fi
     
-    # Add to results
-    RESULTS=$(echo "$RESULTS" | jq --arg method "$method" \
-        --arg path "$path" \
-        --arg desc "$description" \
-        --arg status "$http_code" \
-        --arg format "$format" \
-        --argjson body "$(echo "$body" | jq -c . 2>/dev/null || echo 'null')" \
-        '. += [{
-            method: $method,
-            path: $path,
-            description: $desc,
-            status: $status,
-            format: $format,
-            response_sample: $body
-        }]')
+    # Add to results (handle non-JSON responses)
+    local body_json="null"
+    if [ -n "$body" ]; then
+        # Try to parse as JSON first
+        if echo "$body" | jq . >/dev/null 2>&1; then
+            body_json=$(echo "$body" | jq -c .)
+        else
+            # Not valid JSON, store as escaped string (truncate to 200 chars)
+            body_json=$(echo "$body" | head -c 200 | jq -Rs .)
+        fi
+    fi
+    
+    # Use conditional jq based on whether body_json is null
+    if [ "$body_json" = "null" ]; then
+        RESULTS=$(echo "$RESULTS" | jq --arg method "$method" \
+            --arg path "$path" \
+            --arg desc "$description" \
+            --arg status "$http_code" \
+            --arg format "$format" \
+            '. += [{
+                method: $method,
+                path: $path,
+                description: $desc,
+                status: $status,
+                format: $format,
+                response_sample: null
+            }]')
+    else
+        RESULTS=$(echo "$RESULTS" | jq --arg method "$method" \
+            --arg path "$path" \
+            --arg desc "$description" \
+            --arg status "$http_code" \
+            --arg format "$format" \
+            --argjson body "$body_json" \
+            '. += [{
+                method: $method,
+                path: $path,
+                description: $desc,
+                status: $status,
+                format: $format,
+                response_sample: $body
+            }]')
+    fi
 }
 
 # Extract endpoints from Swagger spec if available
 if [ -n "$SWAGGER_SPEC" ] && [ -f "$SWAGGER_SPEC" ]; then
     echo -e "${GREEN}📋 Reading endpoints from Swagger spec...${NC}"
     
-    # Get all paths
-    jq -r '.paths | to_entries[] | .key as $path | .value | to_entries[] | "\(.key | ascii_upcase) \($path)"' "$SWAGGER_SPEC" | while read -r method path; do
+    # Get all paths and store in temp file to avoid subshell issues
+    TMP_ENDPOINTS=$(mktemp)
+    jq -r '.paths | to_entries[] | .key as $path | .value | to_entries[] | "\(.key | ascii_upcase) \($path)"' "$SWAGGER_SPEC" > "$TMP_ENDPOINTS"
+    
+    # Process endpoints
+    while IFS= read -r line; do
+        method=$(echo "$line" | cut -d' ' -f1)
+        path=$(echo "$line" | cut -d' ' -f2-)
+        
         # Get description if available
         desc=$(jq -r ".paths[\"$path\"][\"${method,,}\"].summary // .paths[\"$path\"][\"${method,,}\"].description // \"\"" "$SWAGGER_SPEC" 2>/dev/null || echo "")
         
@@ -152,7 +187,9 @@ if [ -n "$SWAGGER_SPEC" ] && [ -f "$SWAGGER_SPEC" ]; then
         
         test_endpoint "$method" "$path" "$desc"
         sleep 0.1  # Small delay to avoid overwhelming the server
-    done
+    done < "$TMP_ENDPOINTS"
+    
+    rm -f "$TMP_ENDPOINTS"
 else
     echo -e "${YELLOW}⚠️  No Swagger spec, testing common endpoints manually...${NC}"
     

veza-backend-api/docs/ENDPOINT_FORMAT_AUDIT.md

@@ -0,0 +1,89 @@
+# Endpoint Response Format Audit
+
+**Date**: 2025-01-27  
+**Action**: 1.3.1.2 - Identify endpoints returning direct format  
+**Status**: ✅ Complete
+
+## Overview
+
+This document identifies endpoints that return inconsistent response formats (direct vs wrapped `{ success, data }` format).
+
+## Testing Methodology
+
+- **Script**: `scripts/test-endpoint-formats.sh`
+- **Base URL**: `http://localhost:8080/api/v1`
+- **Source**: Endpoints extracted from `veza-backend-api/docs/swagger.json`
+- **Test Date**: 2025-01-27
+
+## Summary
+
+- **Total Tested**: 36 endpoints
+- **Wrapped Format** (`{ success, data }`): 2 endpoints ✅
+- **Direct Format**: 0 endpoints ⚠️
+- **Auth Required** (401/403): 22 endpoints 🔒
+- **Errors** (404/500): 12 endpoints ❌
+
+## Endpoints with Wrapped Format ✅
+
+These endpoints correctly return `{ success, data }` format:
+
+1. **GET /users** - Status: 200, Format: wrapped
+2. **GET /tracks** - Status: 200, Format: wrapped
+
+## Endpoints Requiring Authentication 🔒
+
+The following endpoints require authentication (401/403), so their format could not be verified without credentials:
+
+- GET /analytics
+- POST /analytics/events
+- GET /analytics/tracks/top
+- GET /webhooks
+- POST /webhooks
+- GET /webhooks/stats
+- ... (22 total)
+
+**Note**: To fully audit these endpoints, authentication tokens are required.
+
+## Endpoints with Errors ❌
+
+The following endpoints returned errors (404/500):
+
+- POST /api/v1/logs/frontend - 404 Not Found
+- ... (12 total)
+
+**Note**: Some endpoints may not exist or may have incorrect paths in the Swagger spec.
+
+## Endpoints Skipped
+
+Endpoints with path parameters were skipped (cannot be tested without specific IDs):
+- GET /tracks/{id}
+- PUT /tracks/{id}
+- DELETE /tracks/{id}
+- GET /users/{id}
+- ... (many more)
+
+## Findings
+
+1. **Consistency**: The 2 endpoints that were successfully tested both use wrapped format ✅
+2. **Coverage**: Most endpoints require authentication, limiting test coverage
+3. **Path Parameters**: Many endpoints have path parameters and cannot be tested without specific IDs
+
+## Recommendations
+
+1. **Authenticated Testing**: Run tests with valid auth tokens to verify format of protected endpoints
+2. **Path Parameter Testing**: Test endpoints with path parameters using known IDs (e.g., test user ID, test track ID)
+3. **Error Handling**: Verify that error responses also use consistent format
+4. **Documentation**: Update Swagger spec to clearly document response format expectations
+
+## Next Steps
+
+- **Action 1.3.1.3**: Categorize endpoints by format type (requires authenticated testing)
+- **Action 1.3.2.1**: Update backend handlers to use wrapped format (if inconsistencies found)
+- **Action 1.3.2.2**: Remove dual-format handling from frontend (after backend is consistent)
+
+## Validation
+
+✅ Script executed successfully  
+✅ Report generated: `endpoint-formats-report.json`  
+⚠️ Limited coverage due to authentication requirements  
+⚠️ Path parameters prevent testing many endpoints