feat(util): add Sbx.create() factory for entity instantiation

Eliminates need for convenience constructors in records.
Sbx.create() auto-sets key and meta to null via reflection.

Author: HansOspina

README.md

@@ -17,7 +17,7 @@ Java 21+ client for SBX Cloud APIs. Spring Boot 3.x compatible.
 <dependency>
     <groupId>com.github.socobox</groupId>
     <artifactId>sbxcloud-lib-java</artifactId>
-    <version>v0.0.11</version>
+    <version>v0.0.13</version>
 </dependency>
 ```
 
@@ -29,7 +29,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.github.socobox:sbxcloud-lib-java:v0.0.11'
+    implementation 'com.github.socobox:sbxcloud-lib-java:v0.0.13'
 }
 ```
 
@@ -51,13 +51,7 @@ public record Contact(
     String name,
     String email,
     String status
-) implements SbxEntity {
-
-    // Constructor for creating new records (without key/meta)
-    public Contact(String name, String email, String status) {
-        this(null, null, name, email, status);
-    }
-}
+) implements SbxEntity {}
 ```
 
 ### 2. Initialize the Service
@@ -81,8 +75,8 @@ var sbx = SBXServiceFactory.builder()
 // Get typed repository
 SbxRepository<Contact> contacts = sbx.repository(Contact.class);
 
-// Create (meta is ignored, null values are ignored)
-var contact = new Contact("John Doe", "john@example.com", "ACTIVE");
+// Create using Sbx.create() - automatically sets key and meta to null
+var contact = Sbx.create(Contact.class, "John Doe", "john@example.com", "ACTIVE");
 String key = contacts.save(contact);
 
 // Read
@@ -211,22 +205,19 @@ The `@SbxModel` annotation automatically:
 - Ignores unknown JSON properties
 - Strips null values (enables partial updates)
 
-### With Convenience Constructor
+### Creating Entities with Sbx.create()
+
+Instead of manual convenience constructors, use `Sbx.create()`:
 
 ```java
-@SbxModel("contact")
-public record Contact(
-    String key,
-    SBXMeta meta,
-    String name,
-    String email
-) implements SbxEntity {
+// No need to add a convenience constructor to your record!
+// Sbx.create() automatically sets key and meta to null
 
-    // For creating new records
-    public Contact(String name, String email) {
-        this(null, null, name, email);
-    }
-}
+var contact = Sbx.create(Contact.class, "John", "john@example.com");
+// Equivalent to: new Contact(null, null, "John", "john@example.com")
+
+// Pass field values in order (excluding key and meta)
+String key = contacts.save(contact);
 ```
 
 ### Without Repository (Manual Jackson)
@@ -269,6 +260,9 @@ sbx.delete("contact", List.of("k1", "k2", "k3"));
 ```java
 import static com.sbxcloud.sbx.util.Sbx.*;
 
+// Create entities (automatically sets key and meta to null)
+var contact = create(Contact.class, "John", "john@example.com", "ACTIVE");
+
 // JSON conversion
 String json = toJson(entity);
 String pretty = toPrettyJson(entity);

src/main/java/com/sbxcloud/sbx/util/Sbx.java

@@ -6,8 +6,12 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import com.sbxcloud.sbx.annotation.SbxEntity;
 import com.sbxcloud.sbx.jackson.SbxModule;
+import com.sbxcloud.sbx.model.SBXMeta;
 
+import java.lang.reflect.Constructor;
+import java.lang.reflect.RecordComponent;
 import java.util.Map;
 
 /**
@@ -106,6 +110,66 @@ public static <T> T fromMap(Map<String, Object> map, Class<T> type) {
         return MAPPER.convertValue(map, type);
     }
 
+    /**
+     * Creates a new entity instance, automatically setting key and meta to null.
+     * <p>
+     * Pass only the data fields (excluding key and meta) in the order they appear
+     * in the record definition.
+     *
+     * <pre>{@code
+     * // Instead of:
+     * new Contact(null, null, "John", "john@example.com", "ACTIVE")
+     *
+     * // Use:
+     * Sbx.create(Contact.class, "John", "john@example.com", "ACTIVE")
+     * }</pre>
+     *
+     * @param type   the entity class (must be a record implementing SbxEntity)
+     * @param values the field values (excluding key and meta)
+     * @return new entity instance with key=null, meta=null
+     */
+    @SuppressWarnings("unchecked")
+    public static <T extends SbxEntity> T create(Class<T> type, Object... values) {
+        if (!type.isRecord()) {
+            throw new SbxUtilException("Class must be a record: " + type.getName(), null);
+        }
+
+        RecordComponent[] components = type.getRecordComponents();
+        Class<?>[] paramTypes = new Class<?>[components.length];
+        Object[] args = new Object[components.length];
+
+        int valueIndex = 0;
+        for (int i = 0; i < components.length; i++) {
+            RecordComponent comp = components[i];
+            paramTypes[i] = comp.getType();
+
+            // Skip key and meta - set to null
+            if ("key".equals(comp.getName()) || "meta".equals(comp.getName())) {
+                args[i] = null;
+            } else {
+                if (valueIndex >= values.length) {
+                    throw new SbxUtilException(
+                            "Not enough values provided. Expected " + (components.length - 2) +
+                                    " but got " + values.length, null);
+                }
+                args[i] = values[valueIndex++];
+            }
+        }
+
+        if (valueIndex < values.length) {
+            throw new SbxUtilException(
+                    "Too many values provided. Expected " + (components.length - 2) +
+                            " but got " + values.length, null);
+        }
+
+        try {
+            Constructor<T> constructor = type.getDeclaredConstructor(paramTypes);
+            return constructor.newInstance(args);
+        } catch (Exception e) {
+            throw new SbxUtilException("Failed to create entity: " + type.getName(), e);
+        }
+    }
+
     /**
      * Runtime exception for utility operations.
      */

src/test/java/com/sbxcloud/sbx/SBXIntegrationTest.java

@@ -5,6 +5,7 @@
 import com.sbxcloud.sbx.model.InventoryHistory;
 import com.sbxcloud.sbx.query.FindQuery;
 import com.sbxcloud.sbx.repository.SbxRepository;
+import com.sbxcloud.sbx.util.Sbx;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.MethodOrderer;
@@ -209,8 +210,9 @@ void testSimpleFindWithClass() {
     @Test
     @Order(12)
     void testCreateWithEntity() {
-        // Create entity using constructor
-        var entity = new InventoryHistory("test-entity-" + System.currentTimeMillis(), 20250126, 3.99, 100);
+        // Create entity using Sbx.create() - no manual constructor needed
+        var entity = Sbx.create(InventoryHistory.class,
+                "test-entity-" + System.currentTimeMillis(), 20250126, 3.99, 100);
 
         var response = sbx.create(entity);
 
@@ -239,14 +241,14 @@ void testUpdateWithEntity() {
 
         var existing = findResponse.results().get(0);
 
-        // Create updated entity with new price
+        // Partial update - only key and changed field (price)
         var updated = new InventoryHistory(
                 existing.key(),
-                existing.meta(),
-                existing.masterlist(),
-                existing.week(),
-                9.99, // new price
-                existing.quantity()
+                null,  // meta is ignored
+                null,  // masterlist unchanged
+                null,  // week unchanged
+                9.99,  // new price
+                null   // quantity unchanged
         );
 
         var response = sbx.update(updated);
@@ -283,8 +285,9 @@ void testDeleteWithEntity() {
     @Test
     @Order(15)
     void testDeleteWithClassAndKey() {
-        // Create a new record to delete
-        var entity = new InventoryHistory("delete-test-" + System.currentTimeMillis(), 20250126, 0.99, 1);
+        // Create a new record to delete using Sbx.create()
+        var entity = Sbx.create(InventoryHistory.class,
+                "delete-test-" + System.currentTimeMillis(), 20250126, 0.99, 1);
         var createResponse = sbx.create(entity);
         assertTrue(createResponse.success());
 
@@ -315,8 +318,9 @@ void testRepositoryFindAll() {
     void testRepositorySaveAndFindById() {
         SbxRepository<InventoryHistory> repo = sbx.repository(InventoryHistory.class);
 
-        // Create
-        var entity = new InventoryHistory("repo-test-" + System.currentTimeMillis(), 20250126, 5.99, 25);
+        // Create using Sbx.create()
+        var entity = Sbx.create(InventoryHistory.class,
+                "repo-test-" + System.currentTimeMillis(), 20250126, 5.99, 25);
         String key = repo.save(entity);
 
         assertNotNull(key);

src/test/java/com/sbxcloud/sbx/model/InventoryHistory.java

@@ -6,22 +6,17 @@
 /**
  * Test model for inventory_history records in SBX domain 96.
  * <p>
- * Single annotation does everything - no @JsonProperty, @JsonNaming, or @JsonIgnoreProperties needed!
+ * No convenience constructor needed - use Sbx.create() instead:
+ * <pre>{@code
+ * var entity = Sbx.create(InventoryHistory.class, "masterlist", 20250126, 1.99, 100);
+ * }</pre>
  */
 @SbxModel("inventory_history")
 public record InventoryHistory(
-        String key,           // Auto-mapped to _KEY
-        SBXMeta meta,         // Auto-mapped to _META
+        String key,
+        SBXMeta meta,
         String masterlist,
         Integer week,
         Double price,
         Integer quantity
-) implements SbxEntity {
-
-    /**
-     * Convenience constructor for creating new entities (without key/meta).
-     */
-    public InventoryHistory(String masterlist, Integer week, Double price, Integer quantity) {
-        this(null, null, masterlist, week, price, quantity);
-    }
-}
+) implements SbxEntity {}