feat(response): add typed getFetched() for related entities

- getFetched(Class) returns List<T> of fetched related entities
- getFetchedByKey(Class, key) returns single entity by key
- Type-safe access to fetchedResults using @SbxModel annotation

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.14</version>
+    <version>v0.0.15</version>
 </dependency>
 ```
 
@@ -29,7 +29,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.github.socobox:sbxcloud-lib-java:v0.0.14'
+    implementation 'com.github.socobox:sbxcloud-lib-java:v0.0.15'
 }
 ```
 
@@ -146,6 +146,13 @@ repo.query().where(...).count()          // long
 repo.query().where(...).exists()         // boolean
 repo.query().where(...).execute()        // SBXFindResponse<T>
 
+// Fetching related entities (type-safe!)
+var response = repo.query()
+    .fetch("account", "department")
+    .execute();
+List<Account> accounts = response.getFetched(Account.class);
+Account acc = response.getFetchedByKey(Account.class, contact.account());
+
 // Shortcuts
 repo.findWhere(q -> q.andWhereIsEqualTo("status", "ACTIVE"))
 repo.query().whereEquals("status", "ACTIVE").first()

src/main/java/com/sbxcloud/sbx/model/SBXFindResponse.java

@@ -2,7 +2,10 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.sbxcloud.sbx.annotation.SbxModels;
+import com.sbxcloud.sbx.util.Sbx;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 
@@ -49,4 +52,74 @@ public String getErrorMessage() {
     public boolean hasMorePages(int currentPage) {
         return totalPages != null && currentPage < totalPages;
     }
+
+    /**
+     * Gets fetched related entities as a typed list.
+     * <p>
+     * When using fetchModels() in your query, related entities are returned
+     * in fetchedResults. This method converts them to typed objects.
+     *
+     * <pre>{@code
+     * var query = FindQuery.from(CartBox.class)
+     *     .fetchModels("purchase")
+     *     .andWhereIsNotNull("purchase");
+     *
+     * var response = sbx.find(query);
+     * List<CartBox> boxes = response.results();
+     * List<Purchase> purchases = response.getFetched(Purchase.class);
+     * }</pre>
+     *
+     * @param type class annotated with @SbxModel
+     * @return list of typed entities, or empty list if none found
+     */
+    public <F> List<F> getFetched(Class<F> type) {
+        if (fetchedResults == null) {
+            return List.of();
+        }
+
+        String modelName = SbxModels.getModelName(type);
+        Map<String, Object> modelData = fetchedResults.get(modelName);
+
+        if (modelData == null || modelData.isEmpty()) {
+            return List.of();
+        }
+
+        List<F> result = new ArrayList<>();
+        for (Object value : modelData.values()) {
+            result.add(Sbx.mapper().convertValue(value, type));
+        }
+        return result;
+    }
+
+    /**
+     * Gets a single fetched entity by its key.
+     *
+     * <pre>{@code
+     * var box = response.results().get(0);
+     * Purchase purchase = response.getFetchedByKey(Purchase.class, box.purchase());
+     * }</pre>
+     *
+     * @param type class annotated with @SbxModel
+     * @param key  the entity key
+     * @return the typed entity, or null if not found
+     */
+    public <F> F getFetchedByKey(Class<F> type, String key) {
+        if (fetchedResults == null || key == null) {
+            return null;
+        }
+
+        String modelName = SbxModels.getModelName(type);
+        Map<String, Object> modelData = fetchedResults.get(modelName);
+
+        if (modelData == null) {
+            return null;
+        }
+
+        Object value = modelData.get(key);
+        if (value == null) {
+            return null;
+        }
+
+        return Sbx.mapper().convertValue(value, type);
+    }
 }

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

@@ -188,13 +188,14 @@ void testFindAll() {
     @Order(10)
     void testFindWithAnnotatedClass() {
         // Uses @SbxModel annotation to infer model name
+        // Type is inferred - no need to pass class twice!
         var query = FindQuery.from(InventoryHistory.class)
                 .setPageSize(5);
 
-        var response = sbx.find(query, InventoryHistory.class);
+        var response = sbx.find(query);  // Type inferred from query
 
         assertTrue(response.success(), "Find with annotated class should succeed: " + response.error());
-        System.out.println("Found " + (response.results() != null ? response.results().size() : 0) + " records using @SbxModel");
+        System.out.println("Found " + (response.results() != null ? response.results().size() : 0) + " records using typed FindQuery");
     }
 
     @Test