feat: support username on POST mapping

Author: gsanchietti

README.md

@@ -49,22 +49,7 @@ For debugging mapping and API issues, set `LOGLEVEL=DEBUG` to see detailed trace
 
 You can pre-load SMS-to-Matrix mappings at startup by providing a `MAPPING_FILE` environment variable pointing to a JSON file. This is useful for initializing the proxy with a set of known mappings.
 
-The JSON file should be an array of mapping objects:
-
-```json
-[
-  {
-    "sms_number": "91201",
-    "matrix_id": "@giacomo:synapse.gs.nethserver.net",
-    "room_id": "!giacomo-room:synapse.gs.nethserver.net"
-  },
-  {
-    "sms_number": "91202",
-    "matrix_id": "@mario:synapse.gs.nethserver.net",
-    "room_id": "!mario-room:synapse.gs.nethserver.net"
-  }
-]
-```
+See `docs/example-mappings.json` for an example format.
 
 Usage:
 

docs/openapi.yaml

@@ -229,6 +229,9 @@ components:
         room_id:
           type: string
           description: Matrix room ID where the mapped identifier should route messages.
+        user_name:
+          type: string
+          description: Optional human-friendly name to expose for this mapping (e.g., contact name).
     MappingResponse:
       type: object
       properties:
@@ -238,6 +241,9 @@ components:
           type: string
         room_id:
           type: string
+        user_name:
+          type: string
+          description: Optional human-friendly name associated with the mapping.
         updated_at:
           type: string
           format: date-time

main_test.go

@@ -494,6 +494,68 @@ func TestIntegration_MappingAPI(t *testing.T) {
 		}
 	})
 
+	t.Run("CreateAndGetMappingWithUserName", func(t *testing.T) {
+		headers := map[string]string{
+			"X-Super-Admin-Token": cfg.adminToken,
+		}
+
+		mappingReq := models.MappingRequest{
+			SMSNumber: "+1234509876",
+			MatrixID:  fmt.Sprintf("@userwithname:%s", serverName),
+			RoomID:    fmt.Sprintf("!roomwithname:%s", serverName),
+			UserName:  "Mario Rossi",
+		}
+
+		// Create mapping with user_name
+		resp, body, err := doRequest("POST", baseURL+"/api/internal/map_sms_to_matrix", mappingReq, headers)
+		if err != nil {
+			t.Fatalf("request failed: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			// Try variants if creation failed due to environment
+			if resp.StatusCode == http.StatusBadRequest {
+				if v, err := ensureMappingVariants(t, baseURL, cfg.adminToken, mappingReq.SMSNumber, mappingReq.MatrixID, mappingReq.RoomID); err == nil {
+					t.Logf("created mapping variant %s for sms_number %s", v, mappingReq.SMSNumber)
+				} else {
+					t.Skip("mapping creation failed in this environment; skipping assertion")
+				}
+			}
+			if resp.StatusCode != http.StatusOK {
+				t.Fatalf("unexpected status code %d: %s", resp.StatusCode, string(body))
+			}
+		}
+
+		// Retrieve mapping and check user_name
+		resp, body, err = doRequest("GET", baseURL+"/api/internal/map_sms_to_matrix?sms_number=%2B1234509876", nil, headers)
+		if err != nil {
+			t.Fatalf("request failed: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			if resp.StatusCode == http.StatusBadRequest {
+				if _, err := ensureMappingVariants(t, baseURL, cfg.adminToken, mappingReq.SMSNumber, mappingReq.MatrixID, mappingReq.RoomID); err == nil {
+					// retry GET
+					resp, body, err = doRequest("GET", baseURL+"/api/internal/map_sms_to_matrix?sms_number=%2B1234509876", nil, headers)
+					if err != nil {
+						t.Fatalf("request failed: %v", err)
+					}
+				} else {
+					t.Skip("mapping not found and creation attempts failed; skipping assertion")
+				}
+			}
+			if resp.StatusCode != http.StatusOK {
+				t.Fatalf("unexpected status code %d: %s", resp.StatusCode, string(body))
+			}
+		}
+
+		var mappingResp models.MappingResponse
+		if err := json.Unmarshal(body, &mappingResp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+		if mappingResp.UserName != "Mario Rossi" {
+			t.Errorf("expected user_name='Mario Rossi', got '%s'", mappingResp.UserName)
+		}
+	})
+
 	t.Run("UnauthorizedAccess", func(t *testing.T) {
 		mappingReq := models.MappingRequest{
 			SMSNumber: "+1111111111",

models/mapping.go

@@ -13,5 +13,6 @@ type MappingResponse struct {
 	SMSNumber string `json:"sms_number"`
 	MatrixID  string `json:"matrix_id"`
 	RoomID    string `json:"room_id"`
+	UserName  string `json:"user_name,omitempty"`
 	UpdatedAt string `json:"updated_at"`
 }

models/models_test.go

@@ -54,6 +54,7 @@ func TestMappingRequest_Marshal(t *testing.T) {
 		SMSNumber: "+1234567890",
 		MatrixID:  "@user:example.com",
 		RoomID:    "!room:example.com",
+		UserName:  "Test User",
 	}
 
 	data, err := json.Marshal(req)
@@ -66,6 +67,7 @@ func TestMappingRequest_Marshal(t *testing.T) {
 	assert.Equal(t, req.SMSNumber, req2.SMSNumber)
 	assert.Equal(t, req.MatrixID, req2.MatrixID)
 	assert.Equal(t, req.RoomID, req2.RoomID)
+	assert.Equal(t, req.UserName, req2.UserName)
 }
 
 func TestMessage_Marshal(t *testing.T) {
@@ -138,6 +140,7 @@ func TestMappingResponse_Marshal(t *testing.T) {
 		SMSNumber: "+1234567890",
 		MatrixID:  "@user:example.com",
 		RoomID:    "!room:example.com",
+		UserName:  "Test User",
 		UpdatedAt: "2025-01-01T00:00:00Z",
 	}
 

service/messages.go

@@ -350,6 +350,7 @@ func (s *MessageService) SaveMapping(req *models.MappingRequest) (*models.Mappin
 		SMSNumber: smsNumber,
 		MatrixID:  strings.TrimSpace(req.MatrixID),
 		RoomID:    id.RoomID(roomID),
+		UserName:  strings.TrimSpace(req.UserName),
 		UpdatedAt: s.now(),
 	}
 	entry = s.setMapping(entry)
@@ -399,6 +400,7 @@ func (s *MessageService) buildMappingResponse(entry mappingEntry) *models.Mappin
 		SMSNumber: entry.SMSNumber,
 		MatrixID:  entry.MatrixID,
 		RoomID:    string(entry.RoomID),
+		UserName:  entry.UserName,
 		UpdatedAt: entry.UpdatedAt.UTC().Format(time.RFC3339),
 	}
 }