feat(annotation): add @SbxModel and SbxEntity for type-safe model operations

- Add @SbxModel annotation for mapping classes to SBX model names
- Add SbxEntity interface for standard key/meta fields in records
- Add SbxModels utility for extracting model names from annotations
- Add FindQuery.from(Class<?>) to infer model from annotation
- Add type-safe SBXService methods: find(Class), create(entity),
  update(entity), delete(entity), delete(Class, keys)
- Update InventoryHistory test model to use annotations

Author: HansOspina

src/main/java/com/sbxcloud/sbx/annotation/SbxEntity.java

@@ -0,0 +1,36 @@
+package com.sbxcloud.sbx.annotation;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.sbxcloud.sbx.model.SBXMeta;
+
+/**
+ * Interface for SBX entities with standard key and meta fields.
+ * <p>
+ * Records implementing this interface automatically get the standard SBX fields.
+ * Use with @SbxModel for full annotation support.
+ *
+ * <pre>{@code
+ * @SbxModel("inventory_history")
+ * @JsonIgnoreProperties(ignoreUnknown = true)
+ * public record InventoryHistory(
+ *         @JsonProperty("_KEY") String key,
+ *         @JsonProperty("_META") SBXMeta meta,
+ *         String masterlist,
+ *         Integer week
+ * ) implements SbxEntity {}
+ * }</pre>
+ */
+public interface SbxEntity {
+
+    /**
+     * Returns the SBX primary key (_KEY).
+     */
+    @JsonProperty("_KEY")
+    String key();
+
+    /**
+     * Returns the SBX metadata (_META).
+     */
+    @JsonProperty("_META")
+    SBXMeta meta();
+}

src/main/java/com/sbxcloud/sbx/annotation/SbxModel.java

@@ -0,0 +1,30 @@
+package com.sbxcloud.sbx.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a class as an SBX model and specifies its row_model name.
+ *
+ * <pre>{@code
+ * @SbxModel("inventory_history")
+ * public record InventoryHistory(
+ *     @JsonProperty("_KEY") String key,
+ *     @JsonProperty("_META") SBXMeta meta,
+ *     String masterlist,
+ *     Integer week,
+ *     Double price,
+ *     Integer quantity
+ * ) {}
+ * }</pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface SbxModel {
+    /**
+     * The SBX row_model name.
+     */
+    String value();
+}

src/main/java/com/sbxcloud/sbx/annotation/SbxModels.java

@@ -0,0 +1,33 @@
+package com.sbxcloud.sbx.annotation;
+
+/**
+ * Utility for working with @SbxModel annotations.
+ */
+public final class SbxModels {
+
+    private SbxModels() {}
+
+    /**
+     * Extracts the model name from a class annotated with @SbxModel.
+     *
+     * @param type the annotated class
+     * @return the model name
+     * @throws IllegalArgumentException if class is not annotated with @SbxModel
+     */
+    public static String getModelName(Class<?> type) {
+        var annotation = type.getAnnotation(SbxModel.class);
+        if (annotation == null) {
+            throw new IllegalArgumentException(
+                "Class " + type.getName() + " is not annotated with @SbxModel"
+            );
+        }
+        return annotation.value();
+    }
+
+    /**
+     * Checks if a class is annotated with @SbxModel.
+     */
+    public static boolean isAnnotated(Class<?> type) {
+        return type.isAnnotationPresent(SbxModel.class);
+    }
+}

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

@@ -5,6 +5,8 @@
 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.annotation.SbxModels;
 import com.sbxcloud.sbx.exception.SBXException;
 import com.sbxcloud.sbx.model.*;
 import com.sbxcloud.sbx.query.FindQuery;
@@ -201,6 +203,119 @@ public SBXResponse<Void> delete(String model, String key) {
         return delete(model, List.of(key));
     }
 
+    // ==================== Type-safe Operations (with @SbxModel) ====================
+
+    /**
+     * Finds all records for an @SbxModel annotated class.
+     *
+     * @param type class annotated with @SbxModel
+     * @return find response with results
+     */
+    public <T> SBXFindResponse<T> find(Class<T> type) {
+        return find(FindQuery.from(type), type);
+    }
+
+    /**
+     * Creates a new record from an @SbxModel annotated entity.
+     * Model name is inferred from the @SbxModel annotation.
+     *
+     * @param entity the entity to create
+     * @return response with created key
+     */
+    public <T> SBXResponse<T> create(T entity) {
+        String model = SbxModels.getModelName(entity.getClass());
+        Map<String, Object> row = objectMapper.convertValue(entity, new TypeReference<>() {});
+        return create(model, row);
+    }
+
+    /**
+     * Creates multiple records from @SbxModel annotated entities.
+     * Model name is inferred from the @SbxModel annotation of the first entity.
+     *
+     * @param entities the entities to create
+     * @return response with created keys
+     */
+    @SafeVarargs
+    public final <T> SBXResponse<T> create(T... entities) {
+        if (entities == null || entities.length == 0) {
+            return SBXResponse.failure("No entities provided");
+        }
+        String model = SbxModels.getModelName(entities[0].getClass());
+        List<Map<String, Object>> rows = Arrays.stream(entities)
+                .map(e -> objectMapper.convertValue(e, new TypeReference<Map<String, Object>>() {}))
+                .toList();
+        return create(model, rows);
+    }
+
+    /**
+     * Updates an @SbxModel annotated entity.
+     * The entity must have a non-null key.
+     *
+     * @param entity the entity to update
+     * @return response
+     */
+    public <T> SBXResponse<T> update(T entity) {
+        String model = SbxModels.getModelName(entity.getClass());
+        Map<String, Object> row = objectMapper.convertValue(entity, new TypeReference<>() {});
+        return update(model, row);
+    }
+
+    /**
+     * Updates multiple @SbxModel annotated entities.
+     *
+     * @param entities the entities to update
+     * @return response
+     */
+    @SafeVarargs
+    public final <T> SBXResponse<T> update(T... entities) {
+        if (entities == null || entities.length == 0) {
+            return SBXResponse.failure("No entities provided");
+        }
+        String model = SbxModels.getModelName(entities[0].getClass());
+        List<Map<String, Object>> rows = Arrays.stream(entities)
+                .map(e -> objectMapper.convertValue(e, new TypeReference<Map<String, Object>>() {}))
+                .toList();
+        return update(model, rows);
+    }
+
+    /**
+     * Deletes an @SbxEntity by extracting its key.
+     *
+     * @param entity the entity to delete (must implement SbxEntity)
+     * @return response
+     */
+    public <T extends SbxEntity> SBXResponse<Void> delete(T entity) {
+        if (entity.key() == null) {
+            return SBXResponse.failure("Entity has no key");
+        }
+        String model = SbxModels.getModelName(entity.getClass());
+        return delete(model, entity.key());
+    }
+
+    /**
+     * Deletes records by keys using @SbxModel annotation for model name.
+     *
+     * @param type class annotated with @SbxModel
+     * @param keys the keys to delete
+     * @return response
+     */
+    public SBXResponse<Void> delete(Class<?> type, String... keys) {
+        String model = SbxModels.getModelName(type);
+        return delete(model, List.of(keys));
+    }
+
+    /**
+     * Deletes records by keys using @SbxModel annotation for model name.
+     *
+     * @param type class annotated with @SbxModel
+     * @param keys the keys to delete
+     * @return response
+     */
+    public SBXResponse<Void> delete(Class<?> type, List<String> keys) {
+        String model = SbxModels.getModelName(type);
+        return delete(model, keys);
+    }
+
     // ==================== Authentication ====================
 
     /**

src/main/java/com/sbxcloud/sbx/query/FindQuery.java

@@ -1,5 +1,6 @@
 package com.sbxcloud.sbx.query;
 
+import com.sbxcloud.sbx.annotation.SbxModels;
 import com.sbxcloud.sbx.model.*;
 
 import java.util.ArrayList;
@@ -40,12 +41,22 @@ private FindQuery(String model) {
     }
 
     /**
-     * Creates a new query for the given model.
+     * Creates a new query for the given model name.
      */
     public static FindQuery from(String model) {
         return new FindQuery(model);
     }
 
+    /**
+     * Creates a new query for a class annotated with @SbxModel.
+     *
+     * @param type class annotated with @SbxModel
+     * @throws IllegalArgumentException if class is not annotated
+     */
+    public static FindQuery from(Class<?> type) {
+        return new FindQuery(SbxModels.getModelName(type));
+    }
+
     // ==================== Group Operations ====================
 
     /**

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

@@ -4,6 +4,7 @@
 import com.sbxcloud.sbx.model.AndOr;
 import com.sbxcloud.sbx.model.Operation;
 import com.sbxcloud.sbx.model.WhereClause;
+import com.sbxcloud.sbx.model.InventoryHistory;
 import com.sbxcloud.sbx.query.FindQuery;
 import org.junit.jupiter.api.Test;
 
@@ -155,4 +156,25 @@ void shouldEscapePercentInContains() {
         var expr = conditions.groups().get(0).group().get(0);
         assertEquals("%100%", expr.value());
     }
+
+    @Test
+    void shouldBuildQueryFromAnnotatedClass() {
+        // InventoryHistory is annotated with @SbxModel("inventory_history")
+        var query = FindQuery.from(InventoryHistory.class)
+                .andWhereIsGreaterThan("price", 10)
+                .setPageSize(25)
+                .compile();
+
+        assertEquals("inventory_history", query.rowModel());
+        assertNotNull(query.where());
+        assertEquals(25, query.size());
+    }
+
+    @Test
+    void shouldThrowForNonAnnotatedClass() {
+        // String is not annotated with @SbxModel
+        assertThrows(IllegalArgumentException.class, () -> {
+            FindQuery.from(String.class);
+        });
+    }
 }