feat(api): add block and session action filters (#985)

docs/api/version/v13.md

@@ -11,7 +11,7 @@ API version 13 adds entity-spawn lookup support while retaining all API version
 ## Upgrading from API v12
 
 - `LookupOptions` supports material inclusion/exclusion filters for typed container, item, and inventory lookups, and `users(List<String>)` / `excludeUsers(List<String>)` filters for all typed lookups.
-- `LookupOptions` supports `containerActions(List<ContainerAction>)`, `itemActions(List<ItemAction>)`, and `inventoryActions(List<InventoryAction>)` to select events returned by `containerLookup`, `itemLookup`, and `inventoryLookup`, respectively. Each filter only affects its corresponding lookup. Select multiple actions to match any of them, or omit the filter or pass an empty list to keep the default results.
+- `LookupOptions` supports `blockActions(List<BlockAction>)`, `containerActions(List<ContainerAction>)`, `itemActions(List<ItemAction>)`, `inventoryActions(List<InventoryAction>)`, and `sessionActions(List<SessionAction>)` to select events returned by `blockLookup`, `containerLookup`, `itemLookup`, `inventoryLookup`, and `sessionLookup`, respectively. Each filter only affects its corresponding lookup. Select multiple actions to match any of them, or omit the filter or pass an empty list to keep the default results.
 - Added `CoreProtectAction.ENTITY_SPAWN` with action ID `13`.
 - Added `CoreProtectPreLogEvent.Action.ENTITY_SPAWN`.
 - `BlockResult#getEntityType()` recognizes entity-spawn results.
@@ -27,6 +27,8 @@ Command filters present boats and minecarts as block changes: `a:+block` include
 
 Entity-container location filters match either the transaction's immutable original location or the entity's persisted current/final location, and typed results expose the persisted current/final location. The persisted position is checkpointed when a transaction is logged and during relevant entity lifecycle changes; the synchronous typed APIs do not schedule blocking live-entity scans.
 
+Use `blockActions(List.of(BlockAction.BREAK))` to find broken blocks, or select `BlockAction.PLACE` or `BlockAction.INTERACTION` for placements or interactions. Use `sessionActions(List.of(SessionAction.LOGIN))` for player logins or `SessionAction.LOGOUT` for logouts.
+
 To find items deposited into containers, use `containerActions(List.of(ContainerAction.ADD))`. For inventory lookups, select `InventoryAction.CONTAINER_ADD` for deposits or `InventoryAction.BLOCK_PLACE` for block placement. Container filters also cover tracked boat and minecart transactions.
 
 For example, `itemActions(List.of(ItemAction.DROP, ItemAction.PICKUP))` selects dropped and picked-up items. To query `ItemAction.BREAK`, `DESTROY`, `CREATE`, `SELL`, or `BUY`, select them explicitly with `itemActions`; these events are not included by default.

src/main/java/net/coreprotect/api/BlockAPI.java

@@ -163,6 +163,7 @@ public class BlockAPI {
                 query.append(" AND ").append(ConfigHandler.databaseType.getUserColumn()).append(" = ?");
             }
             LookupFilter.appendUserWhere(query, "", LookupFilter.userIds(connection, options.getUsers()), LookupFilter.userIds(connection, options.getExcludeUsers()));
+            LookupFilter.appendActionWhere(query, "", options.getBlockActions().stream().mapToInt(BlockAction::id).toArray());
             query.append(" ORDER BY ").append(ConfigHandler.getDescendingEventOrder());
             if (options.hasLimit()) {
                 query.append(" LIMIT ").append(options.getLimitCount()).append(" OFFSET ").append(options.getLimitOffset());

src/main/java/net/coreprotect/api/BlockAction.java

@@ -0,0 +1,22 @@
+package net.coreprotect.api;
+
+import net.coreprotect.model.action.LookupActions;
+
+/**
+ * Block actions used by typed block lookup filters.
+ */
+public enum BlockAction {
+    BREAK(LookupActions.BLOCK_BREAK),
+    PLACE(LookupActions.BLOCK_PLACE),
+    INTERACTION(LookupActions.INTERACTION);
+
+    private final int id;
+
+    BlockAction(int id) {
+        this.id = id;
+    }
+
+    public int id() {
+        return id;
+    }
+}

src/main/java/net/coreprotect/api/LookupOptions.java

@@ -22,6 +22,8 @@ public final class LookupOptions {
     private final List<ContainerAction> containerActions;
     private final List<ItemAction> itemActions;
     private final List<InventoryAction> inventoryActions;
+    private final List<BlockAction> blockActions;
+    private final List<SessionAction> sessionActions;
 
     private LookupOptions(Builder builder) {
         this.user = builder.user;
@@ -37,6 +39,8 @@ public final class LookupOptions {
         this.containerActions = builder.containerActions;
         this.itemActions = builder.itemActions;
         this.inventoryActions = builder.inventoryActions;
+        this.blockActions = builder.blockActions;
+        this.sessionActions = builder.sessionActions;
     }
 
     public static Builder builder() {
@@ -99,6 +103,14 @@ public final class LookupOptions {
         return inventoryActions;
     }
 
+    public List<BlockAction> getBlockActions() {
+        return blockActions;
+    }
+
+    public List<SessionAction> getSessionActions() {
+        return sessionActions;
+    }
+
     public static final class Builder {
         private String user;
         private int time;
@@ -113,6 +125,8 @@ public final class LookupOptions {
         private List<ContainerAction> containerActions = List.of();
         private List<ItemAction> itemActions = List.of();
         private List<InventoryAction> inventoryActions = List.of();
+        private List<BlockAction> blockActions = List.of();
+        private List<SessionAction> sessionActions = List.of();
 
         private Builder() {
         }
@@ -180,6 +194,16 @@ public final class LookupOptions {
             return this;
         }
 
+        public Builder blockActions(List<BlockAction> actions) {
+            this.blockActions = List.copyOf(actions);
+            return this;
+        }
+
+        public Builder sessionActions(List<SessionAction> actions) {
+            this.sessionActions = List.copyOf(actions);
+            return this;
+        }
+
         public LookupOptions build() {
             return new LookupOptions(this);
         }

src/main/java/net/coreprotect/api/SessionAction.java

@@ -0,0 +1,21 @@
+package net.coreprotect.api;
+
+import net.coreprotect.model.action.SessionActions;
+
+/**
+ * Session actions used by typed session lookup filters.
+ */
+public enum SessionAction {
+    LOGOUT(SessionActions.LOGOUT),
+    LOGIN(SessionActions.LOGIN);
+
+    private final int id;
+
+    SessionAction(int id) {
+        this.id = id;
+    }
+
+    public int id() {
+        return id;
+    }
+}

src/main/java/net/coreprotect/api/SessionLookup.java

@@ -103,6 +103,10 @@ public class SessionLookup {
             return result;
         }
 
+        if (options == null) {
+            options = LookupOptions.builder().build();
+        }
+
         try (Connection connection = Database.getConnection(false, 1000)) {
             if (connection == null) {
                 return result;
@@ -119,6 +123,7 @@ public class SessionLookup {
                 query.append(WorldUtils.getWidIndex("session"));
             }
             filter.appendWhere(query);
+            LookupFilter.appendActionWhere(query, "", options.getSessionActions().stream().mapToInt(SessionAction::id).toArray());
             query.append(" ORDER BY ").append(ConfigHandler.getDescendingEventOrder());
             filter.appendLimit(query);