fix: strip meta and null values on create/update

- meta/_META is read-only, now always stripped before sending
- null values are stripped, enabling partial updates
- Update README to clarify these behaviors

For updates, only key + changed fields needed:
  new Contact(key, null, "New Name", null, null)

Author: HansOspina

README.md

@@ -81,22 +81,27 @@ var sbx = SBXServiceFactory.builder()
 // Get typed repository
 SbxRepository<Contact> contacts = sbx.repository(Contact.class);
 
-// Create
+// Create (meta is ignored, null values are ignored)
 var contact = new Contact("John Doe", "john@example.com", "ACTIVE");
 String key = contacts.save(contact);
 
 // Read
 Optional<Contact> found = contacts.findById(key);
 List<Contact> all = contacts.findAll();
 
-// Update
-var updated = new Contact(key, found.get().meta(), "John Updated", "john@example.com", "ACTIVE");
-contacts.save(updated);  // Has key, so updates
+// Update - only _KEY and changed fields needed (partial update)
+var updated = new Contact(key, null, "John Updated", null, null);
+contacts.save(updated);  // Only updates name, other fields unchanged
 
 // Delete
 contacts.deleteById(key);
 ```
 
+**Important:**
+- `meta` is read-only and always stripped before create/update
+- `null` values are stripped, enabling partial updates
+- For updates, only `key` + changed fields are required
+
 ---
 
 ## Repository API
@@ -192,8 +197,8 @@ repo.query().whereKeys("k1", "k2").list()
 ```java
 @SbxModel("contact")
 public record Contact(
-    String key,
-    SBXMeta meta,
+    String key,          // Primary key (_KEY) - null for new records
+    SBXMeta meta,        // Read-only metadata (_META) - always null for create/update
     String name,
     String email
 ) implements SbxEntity {}
@@ -202,8 +207,9 @@ public record Contact(
 The `@SbxModel` annotation automatically:
 - Sets the SBX model name for queries
 - Maps `key` → `_KEY` in JSON
-- Maps `meta` → `_META` in JSON
+- Maps `meta` → `_META` in JSON (read-only, stripped on create/update)
 - Ignores unknown JSON properties
+- Strips null values (enables partial updates)
 
 ### With Convenience Constructor
 

src/main/java/com/sbxcloud/sbx/client/SBXService.java

@@ -839,9 +839,9 @@ private <T> SBXResponse<T> upsert(String endpoint, String model, List<Map<String
         }
 
         try {
-            // Clean _META from rows before sending
+            // Clean rows for upsert (remove meta, nulls)
             List<Map<String, Object>> cleanedRows = rows.stream()
-                    .map(this::cleanMeta)
+                    .map(this::cleanForUpsert)
                     .toList();
 
             List<String> allKeys = new ArrayList<>();
@@ -870,9 +870,29 @@ private <T> SBXResponse<T> upsert(String endpoint, String model, List<Map<String
         }
     }
 
-    private Map<String, Object> cleanMeta(Map<String, Object> row) {
-        var cleaned = new LinkedHashMap<>(row);
-        cleaned.remove("_META");
+    /**
+     * Cleans a row for create/update:
+     * - Removes _META/meta (read-only)
+     * - Removes null values (allows partial updates)
+     */
+    private Map<String, Object> cleanForUpsert(Map<String, Object> row) {
+        var cleaned = new LinkedHashMap<String, Object>();
+        for (var entry : row.entrySet()) {
+            String key = entry.getKey();
+            Object value = entry.getValue();
+
+            // Skip meta fields (read-only)
+            if ("_META".equals(key) || "meta".equals(key)) {
+                continue;
+            }
+
+            // Skip null values (allows partial updates)
+            if (value == null) {
+                continue;
+            }
+
+            cleaned.put(key, value);
+        }
         return cleaned;
     }