From 6766122ab20b115062f11fbfb13c3bfea00fc00d Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 11:12:34 +0100
Subject: [PATCH 01/37] Redesign the usage of SlackClient with Builder

---
 pom.xml                                       | 14 ++++-
 readme.md                                     |  4 +-
 .../n1netails/slack/api/SlackClient.java      | 14 ++++-
 .../n1netails/slack/api/SlackClientImpl.java  | 51 +++++++++++++++++++
 .../slack/internal/SlackClientImpl.java       | 30 -----------
 5 files changed, 79 insertions(+), 34 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
 delete mode 100644 src/main/java/com/n1netails/n1netails/slack/internal/SlackClientImpl.java

diff --git a/pom.xml b/pom.xml
index cd876e1..25663ed 100644
--- a/pom.xml
+++ b/pom.xml
@@ -16,8 +16,20 @@
     <connection>scm:git:git://github.com/n1netails/n1netails-slack-client.git</connection>
     <developerConnection>scm:git:ssh://git@github.com:n1netails/n1netails-slack-client.git</developerConnection>
   </scm>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>17</source>
+                    <target>17</target>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
 
-  <licenses>
+    <licenses>
     <license>
       <name>MIT License</name>
       <url>https://opensource.org/licenses/MIT</url>
diff --git a/readme.md b/readme.md
index ded405a..827fc04 100644
--- a/readme.md
+++ b/readme.md
@@ -51,7 +51,7 @@ Here's how to use the client to send a message:
 
 ```java
 import com.n1netails.n1netails.slack.api.SlackClient;
-import com.n1netails.n1netails.slack.internal.SlackClientImpl;
+import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
 import com.n1netails.n1netails.slack.service.BotService;
 
@@ -90,7 +90,7 @@ You can also send more complex messages using [Slack's Block Kit](https://api.sl
 
 ```java
 import com.n1netails.n1netails.slack.api.SlackClient;
-import com.n1netails.n1netails.slack.internal.SlackClientImpl;
+import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
 import com.n1netails.n1netails.slack.service.BotService;
 import com.slack.api.model.block.Blocks;
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
index 527e8da..d8c77ed 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
@@ -5,13 +5,25 @@
 
 /**
  * Slick Client
+ *
  * @author shahid foy
  */
-public interface SlackClient {
+public sealed interface SlackClient permits SlackClientImpl {
 
     /**
      * Send slack message
+     *
      * @param slackMessage slack message
      */
     void sendMessage(SlackMessage slackMessage) throws SlackClientException;
+
+    static Builder builder() {
+        return new SlackClientImpl.Builder();
+    }
+
+    sealed interface Builder permits SlackClientImpl.Builder {
+        Builder token(String token);
+
+        SlackClient build() throws SlackClientException;
+    }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
new file mode 100644
index 0000000..8f9aae7
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
@@ -0,0 +1,51 @@
+package com.n1netails.n1netails.slack.api;
+
+import com.n1netails.n1netails.slack.exception.SlackClientException;
+import com.n1netails.n1netails.slack.model.SlackMessage;
+import com.n1netails.n1netails.slack.service.BotService;
+
+/**
+ * Slack Client Implementation
+ *
+ * @author shahid foy
+ */
+final class SlackClientImpl implements SlackClient {
+
+    private final BotService botService;
+
+    public SlackClientImpl(Builder builder) {
+        this.botService = new BotService(builder.token);
+    }
+
+    /**
+     * Send slack notification
+     *
+     * @param slackMessage slack message
+     */
+    @Override
+    public void sendMessage(SlackMessage slackMessage) throws SlackClientException {
+        try {
+            botService.send(slackMessage);
+        } catch (Exception e) {
+            throw new SlackClientException("Failed to send Slack message", e);
+        }
+    }
+
+    public static final class Builder implements SlackClient.Builder {
+        private String token;
+
+        @Override
+        public SlackClient.Builder token(String token) {
+            this.token = token;
+            return this;
+        }
+
+        @Override
+        public SlackClient build() throws SlackClientException {
+            if (this.token == null || this.token.isBlank())
+                throw new SlackClientException("token must be provided");
+
+            return new SlackClientImpl(this);
+        }
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/internal/SlackClientImpl.java b/src/main/java/com/n1netails/n1netails/slack/internal/SlackClientImpl.java
deleted file mode 100644
index 3550acb..0000000
--- a/src/main/java/com/n1netails/n1netails/slack/internal/SlackClientImpl.java
+++ /dev/null
@@ -1,30 +0,0 @@
-package com.n1netails.n1netails.slack.internal;
-
-import com.n1netails.n1netails.slack.api.SlackClient;
-import com.n1netails.n1netails.slack.exception.SlackClientException;
-import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.service.BotService;
-
-/**
- * Slack Client Implementation
- * @author shahid foy
- */
-public class SlackClientImpl implements SlackClient {
-
-    private final BotService botService;
-
-    public SlackClientImpl(BotService botService) { this.botService = botService; }
-
-    /**
-     * Send slack notification
-     * @param slackMessage slack message
-     */
-    @Override
-    public void sendMessage(SlackMessage slackMessage) throws SlackClientException {
-        try {
-            botService.send(slackMessage);
-        } catch (Exception e) {
-            throw new SlackClientException("Failed to send Slack message", e);
-        }
-    }
-}

From 63937a54af1685639bbc2803ed25e7a4668a56c1 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 11:27:54 +0100
Subject: [PATCH 02/37] Update readme.md

---
 readme.md | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/readme.md b/readme.md
index 827fc04..e112c44 100644
--- a/readme.md
+++ b/readme.md
@@ -53,7 +53,7 @@ Here's how to use the client to send a message:
 import com.n1netails.n1netails.slack.api.SlackClient;
 import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.service.BotService;
+import com.n1netails.n1netails.slack.api.BotService;
 
 public class Example {
     public static void main(String[] args) {
@@ -63,11 +63,8 @@ public class Example {
         // The channel you want to send the message to (e.g., "#general")
         String channel = "#prototype"; // or "#channel-name"
 
-        // Create the bot service
-        BotService botService = new BotService(token);
-
-        // Create the Slack client
-        SlackClient slackClient = new SlackClientImpl(botService);
+        // Use builder to create a client
+        SlackClient client = SlackClient.builder().token(token).build();
 
         // Create the message
         SlackMessage message = new SlackMessage();
@@ -92,7 +89,7 @@ You can also send more complex messages using [Slack's Block Kit](https://api.sl
 import com.n1netails.n1netails.slack.api.SlackClient;
 import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.service.BotService;
+import com.n1netails.n1netails.slack.api.BotService;
 import com.slack.api.model.block.Blocks;
 import com.slack.api.model.block.composition.BlockCompositions;
 
@@ -103,8 +100,7 @@ public class AdvancedExample {
         String token = "xoxb-your-bot-token";
         String channel = "#prototype";
 
-        BotService botService = new BotService(token);
-        SlackClient slackClient = new SlackClientImpl(botService);
+        SlackClient client = SlackClient.builder().token(token).build();
 
         SlackMessage message = new SlackMessage();
         message.setChannel(channel);

From 6d80c6f3fd0f13eedb12ccda7c1e279115ab39df Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 11:28:48 +0100
Subject: [PATCH 03/37] Encapsulation: only SlackClient is available for
 creation

---
 .../n1netails/slack/{service => api}/BotService.java        | 6 ++++--
 .../java/com/n1netails/n1netails/slack/api/SlackClient.java | 1 +
 .../com/n1netails/n1netails/slack/api/SlackClientImpl.java  | 1 -
 3 files changed, 5 insertions(+), 3 deletions(-)
 rename src/main/java/com/n1netails/n1netails/slack/{service => api}/BotService.java (94%)

diff --git a/src/main/java/com/n1netails/n1netails/slack/service/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
similarity index 94%
rename from src/main/java/com/n1netails/n1netails/slack/service/BotService.java
rename to src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 4d3ae8f..6696c58 100644
--- a/src/main/java/com/n1netails/n1netails/slack/service/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -1,4 +1,4 @@
-package com.n1netails.n1netails.slack.service;
+package com.n1netails.n1netails.slack.api;
 
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.model.SlackMessage;
@@ -8,14 +8,16 @@
 
 /**
  * Slack Bot Service
+ *
  * @author shahid foy
  */
-public class BotService {
+class BotService {
 
     private final String token;
 
     /**
      * Bot Service Constructor
+     *
      * @param token slack bot token
      */
     public BotService(String token) {
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
index d8c77ed..4cb0bd9 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.api;
 
+import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.model.SlackMessage;
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
index 8f9aae7..423d8b7 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
@@ -2,7 +2,6 @@
 
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.service.BotService;
 
 /**
  * Slack Client Implementation

From d5ed27b462c3b4d420c53ddd365df78f525a4b4f Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 11:46:17 +0100
Subject: [PATCH 04/37] Prevents recreating client every call

---
 .../java/com/n1netails/n1netails/slack/api/BotService.java  | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 6696c58..2d39cab 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -12,8 +12,7 @@
  * @author shahid foy
  */
 class BotService {
-
-    private final String token;
+    private final MethodsClient methods;
 
     /**
      * Bot Service Constructor
@@ -21,12 +20,11 @@ class BotService {
      * @param token slack bot token
      */
     public BotService(String token) {
-        this.token = token;
+        this.methods = Slack.getInstance().methods(token);
     }
 
     public void send(SlackMessage slackMessage) throws SlackClientException {
         try {
-            MethodsClient methods = Slack.getInstance().methods(token);
             ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder = ChatPostMessageRequest.builder()
                     .channel(slackMessage.getChannel())
                     .text(slackMessage.getText());

From 53db1c853fea7198ea9dbc1341ed036240cde9e8 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 11:57:04 +0100
Subject: [PATCH 05/37] Error handling

---
 .../n1netails/slack/api/BotService.java       | 33 +++++++++++++++----
 .../n1netails/slack/api/SlackClientImpl.java  |  6 +---
 2 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 2d39cab..8da2f79 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -4,7 +4,11 @@
 import com.n1netails.n1netails.slack.model.SlackMessage;
 import com.slack.api.Slack;
 import com.slack.api.methods.MethodsClient;
+import com.slack.api.methods.SlackApiException;
 import com.slack.api.methods.request.chat.ChatPostMessageRequest;
+import com.slack.api.methods.response.chat.ChatPostMessageResponse;
+
+import java.io.IOException;
 
 /**
  * Slack Bot Service
@@ -24,18 +28,35 @@ public BotService(String token) {
     }
 
     public void send(SlackMessage slackMessage) throws SlackClientException {
+        validateSlackMessage(slackMessage);
         try {
-            ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder = ChatPostMessageRequest.builder()
-                    .channel(slackMessage.getChannel())
-                    .text(slackMessage.getText());
+            ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder =
+                    ChatPostMessageRequest.builder()
+                            .channel(slackMessage.getChannel())
+                            .text(slackMessage.getText());
 
             if (slackMessage.getBlocks() != null && !slackMessage.getBlocks().isEmpty()) {
                 requestBuilder.blocks(slackMessage.getBlocks());
             }
 
-            methods.chatPostMessage(requestBuilder.build());
-        } catch (Exception e) {
-            throw new SlackClientException("Failed to send Slack message", e);
+            ChatPostMessageResponse response = methods.chatPostMessage(requestBuilder.build());
+
+            if (!response.isOk()) {
+                throw new SlackClientException("Slack API error: " + response.getError());
+            }
+
+        } catch (IOException | SlackApiException e) {
+            throw new SlackClientException("Failed to send Slack message to channel: " + slackMessage.getChannel(), e);
+        }
+    }
+
+    private void validateSlackMessage(SlackMessage slackMessage) throws SlackClientException {
+        if (slackMessage == null) {
+            throw new SlackClientException("slackMessage cannot be null");
+        }
+
+        if (slackMessage.getChannel() == null || slackMessage.getChannel().isBlank()) {
+            throw new SlackClientException("Channel must be provided");
         }
     }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
index 423d8b7..1e9bebd 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
@@ -23,11 +23,7 @@ public SlackClientImpl(Builder builder) {
      */
     @Override
     public void sendMessage(SlackMessage slackMessage) throws SlackClientException {
-        try {
-            botService.send(slackMessage);
-        } catch (Exception e) {
-            throw new SlackClientException("Failed to send Slack message", e);
-        }
+        botService.send(slackMessage);
     }
 
     public static final class Builder implements SlackClient.Builder {

From 1c4eed41ee9c56808be910ef8521bbf7ea7abe3e Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 13:23:01 +0100
Subject: [PATCH 06/37] Support pics and gifs

---
 .../n1netails/slack/api/BotService.java       | 21 +++++--
 .../n1netails/slack/model/SlackBlock.java     |  9 +++
 .../n1netails/slack/model/SlackMessage.java   | 56 +++++++++++++++++--
 .../slack/model/blocks/GifBlock.java          | 26 +++++++++
 .../slack/model/blocks/ImageBlock.java        | 29 ++++++++++
 5 files changed, 130 insertions(+), 11 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 8da2f79..e1d4aec 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -1,14 +1,19 @@
 package com.n1netails.n1netails.slack.api;
 
 import com.n1netails.n1netails.slack.exception.SlackClientException;
+import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackMessage;
 import com.slack.api.Slack;
 import com.slack.api.methods.MethodsClient;
 import com.slack.api.methods.SlackApiException;
 import com.slack.api.methods.request.chat.ChatPostMessageRequest;
 import com.slack.api.methods.response.chat.ChatPostMessageResponse;
+import com.slack.api.model.block.LayoutBlock;
+import lombok.Getter;
+import lombok.Setter;
 
 import java.io.IOException;
+import java.util.List;
 
 /**
  * Slack Bot Service
@@ -34,9 +39,18 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
                     ChatPostMessageRequest.builder()
                             .channel(slackMessage.getChannel())
                             .text(slackMessage.getText());
+            List<LayoutBlock> finalBlocks = null;
+            if (slackMessage.getRawBlocks() != null && !slackMessage.getRawBlocks().isEmpty()) {
+                finalBlocks = slackMessage.getRawBlocks();
 
-            if (slackMessage.getBlocks() != null && !slackMessage.getBlocks().isEmpty()) {
-                requestBuilder.blocks(slackMessage.getBlocks());
+            } else if (slackMessage.getBlocks() != null && !slackMessage.getBlocks().isEmpty()) {
+                finalBlocks = slackMessage.getBlocks().stream()
+                        .map(SlackBlock::toLayoutBlock)
+                        .toList();
+            }
+
+            if (finalBlocks != null && !finalBlocks.isEmpty()) {
+                requestBuilder.blocks(finalBlocks);
             }
 
             ChatPostMessageResponse response = methods.chatPostMessage(requestBuilder.build());
@@ -55,8 +69,5 @@ private void validateSlackMessage(SlackMessage slackMessage) throws SlackClientE
             throw new SlackClientException("slackMessage cannot be null");
         }
 
-        if (slackMessage.getChannel() == null || slackMessage.getChannel().isBlank()) {
-            throw new SlackClientException("Channel must be provided");
-        }
     }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
new file mode 100644
index 0000000..ced5e45
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
@@ -0,0 +1,9 @@
+package com.n1netails.n1netails.slack.model;
+
+import com.slack.api.model.block.LayoutBlock;
+
+import java.util.List;
+
+public interface SlackBlock {
+    LayoutBlock toLayoutBlock();
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 007f8f7..ecddfeb 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -4,6 +4,7 @@
 import lombok.Getter;
 import lombok.Setter;
 
+import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -11,15 +12,58 @@
  * @author shahid foy
  */
 @Getter
-@Setter
 public class SlackMessage {
 
     private String channel;
     private String text;
-    private List<LayoutBlock> blocks;
+    private List<SlackBlock> blocks;
+    private List<LayoutBlock> rawBlocks;
 
-    /**
-     * Slack Message Constructor
-     */
-    public SlackMessage() {}
+    private SlackMessage(Builder builder) {
+        this.channel = builder.channel;
+        this.text = builder.text;
+        this.blocks = List.copyOf(builder.blocks);
+        this.rawBlocks = List.copyOf(builder.rawBlocks);
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+        private String channel;
+        private String text;
+        private final List<SlackBlock> blocks = new ArrayList<>();
+        private final List<LayoutBlock> rawBlocks = new ArrayList<>();
+
+        public Builder channel(String channel) {
+            this.channel = channel;
+            return this;
+        }
+
+        public Builder text(String text) {
+            this.text = text;
+            return this;
+        }
+
+        public Builder addBlock(SlackBlock block) {
+            this.blocks.add(block);
+            return this;
+        }
+
+        public Builder addRawBlock(LayoutBlock block) {
+            this.rawBlocks.add(block);
+            return this;
+        }
+
+        public SlackMessage build() {
+            if (channel == null || channel.isBlank()) {
+                throw new IllegalStateException("channel is required");
+            }
+            if ((text == null || text.isBlank()) && blocks.isEmpty() && rawBlocks.isEmpty()) {
+                throw new IllegalStateException("Either text, blocks, or rawBlocks must be provided");
+            }
+            return new SlackMessage(this);
+        }
+    }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
new file mode 100644
index 0000000..ba55585
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
@@ -0,0 +1,26 @@
+package com.n1netails.n1netails.slack.model.blocks;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.slack.api.model.block.LayoutBlock;
+import com.slack.api.model.block.composition.PlainTextObject;
+
+public class GifBlock implements SlackBlock {
+    private final String imageUrl;
+    private final String altText;
+
+    public GifBlock(String imageUrl, String altText) {
+        this.imageUrl = imageUrl;
+        this.altText = altText;
+    }
+
+
+    @Override
+    public LayoutBlock toLayoutBlock() {
+        return
+                com.slack.api.model.block.ImageBlock.builder()
+                        .altText(altText)
+                        .imageUrl(imageUrl)
+                        .build()
+                ;
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
new file mode 100644
index 0000000..1a4141c
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
@@ -0,0 +1,29 @@
+package com.n1netails.n1netails.slack.model.blocks;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.LayoutBlock;
+import com.slack.api.model.block.composition.BlockCompositions;
+
+import java.util.List;
+
+public class ImageBlock implements SlackBlock {
+    private final String imageUrl;
+    private final String altText;
+
+    public ImageBlock(String imageUrl, String altText) {
+        this.imageUrl = imageUrl;
+        this.altText = altText;
+    }
+
+
+    @Override
+    public LayoutBlock toLayoutBlock() {
+        return
+                com.slack.api.model.block.ImageBlock.builder()
+                        .imageUrl(imageUrl)
+                        .altText(altText)
+                        .build()
+                ;
+    }
+}

From 51c6ba2062ec64750d3e91efdd49ad86aafe9063 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 13:42:55 +0100
Subject: [PATCH 07/37] Support text

---
 .../slack/model/blocks/TextBlock.java         | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
new file mode 100644
index 0000000..2109046
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
@@ -0,0 +1,20 @@
+package com.n1netails.n1netails.slack.model.blocks;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.slack.api.model.block.LayoutBlock;
+import com.slack.api.model.block.composition.PlainTextObject;
+
+public class TextBlock implements SlackBlock {
+    private final String text;
+
+    public TextBlock(String text) {
+        this.text = text;
+    }
+
+    @Override
+    public LayoutBlock toLayoutBlock() {
+        return com.slack.api.model.block.SectionBlock.builder()
+                .text(new PlainTextObject(text, false))
+                .build();
+    }
+}

From a271562f11df23f1484ed7ba162342edcf1f51e1 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 13:45:21 +0100
Subject: [PATCH 08/37] prevent usage of blocks and rawBlocks together

---
 .../n1netails/n1netails/slack/api/BotService.java  |  5 +++--
 .../n1netails/slack/model/SlackMessage.java        | 14 +++++++++++++-
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index e1d4aec..caa22e6 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -39,7 +39,7 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
                     ChatPostMessageRequest.builder()
                             .channel(slackMessage.getChannel())
                             .text(slackMessage.getText());
-            List<LayoutBlock> finalBlocks = null;
+            List<LayoutBlock> finalBlocks;
             if (slackMessage.getRawBlocks() != null && !slackMessage.getRawBlocks().isEmpty()) {
                 finalBlocks = slackMessage.getRawBlocks();
 
@@ -47,7 +47,8 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
                 finalBlocks = slackMessage.getBlocks().stream()
                         .map(SlackBlock::toLayoutBlock)
                         .toList();
-            }
+            } else
+                finalBlocks = null;
 
             if (finalBlocks != null && !finalBlocks.isEmpty()) {
                 requestBuilder.blocks(finalBlocks);
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index ecddfeb..05d82a0 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -9,6 +9,7 @@
 
 /**
  * Slack Message
+ *
  * @author shahid foy
  */
 @Getter
@@ -60,10 +61,21 @@ public SlackMessage build() {
             if (channel == null || channel.isBlank()) {
                 throw new IllegalStateException("channel is required");
             }
-            if ((text == null || text.isBlank()) && blocks.isEmpty() && rawBlocks.isEmpty()) {
+
+            boolean hasTextOrBlocks = (text != null && !text.isBlank())
+                    || (!blocks.isEmpty())
+                    || (!rawBlocks.isEmpty());
+
+            if (!hasTextOrBlocks) {
                 throw new IllegalStateException("Either text, blocks, or rawBlocks must be provided");
             }
+
+            if (!blocks.isEmpty() && !rawBlocks.isEmpty()) {
+                throw new IllegalStateException("Cannot mix SlackBlock and rawBlocks in the same message");
+            }
+
             return new SlackMessage(this);
         }
+
     }
 }

From f545153289e21af2ad5da24454f465bdfbafc416 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 13:45:39 +0100
Subject: [PATCH 09/37] update readme.md

---
 readme.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/readme.md b/readme.md
index e112c44..255d1c1 100644
--- a/readme.md
+++ b/readme.md
@@ -47,13 +47,15 @@ implementation 'com.n1netails:n1netails-slack-client:0.2.0'
 ```
 
 ## Usage
-Here's how to use the client to send a message:
+Here's how to use the client to send a message, pics or gifs:
 
 ```java
 import com.n1netails.n1netails.slack.api.SlackClient;
 import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
 import com.n1netails.n1netails.slack.api.BotService;
+import com.n1netails.n1netails.slack.model.blocks.GifBlock;
+import com.n1netails.n1netails.slack.model.blocks.TextBlock;
 
 public class Example {
     public static void main(String[] args) {
@@ -67,9 +69,13 @@ public class Example {
         SlackClient client = SlackClient.builder().token(token).build();
 
         // Create the message
-        SlackMessage message = new SlackMessage();
-        message.setChannel(channel);
-        message.setText("Hello from the N1ne Tails Slack Client!");
+        SlackMessage message = SlackMessage.builder()
+                .channel("test")
+                .text("New content 🚀") //Remember if use ANY blocks this text becomes a fallback message for notifications
+                .addBlock(new TextBlock("New content 🚀"))
+                .addBlock(new ImageBlock("YOUR IMG LINK", "YOUR ALT TEXT"))
+                .addBlock(new GifBlock("YOUR GIF LINK", "YOUR ALT TEXT"))
+                .build();
 
         try {
             // Send the message

From 330f1271caffe57d04a14fd82f8e8036b10f27e5 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 20:37:09 +0100
Subject: [PATCH 10/37] Exceptions handling

---
 .../n1netails/n1netails/slack/api/BotService.java  |  9 ++++++---
 .../n1netails/slack/api/SlackClientImpl.java       |  2 +-
 .../slack/exception/SlackApiExceptionWrapper.java  | 14 ++++++++++++++
 .../slack/exception/SlackTransportException.java   |  7 +++++++
 .../slack/exception/SlackValidationException.java  |  7 +++++++
 5 files changed, 35 insertions(+), 4 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/exception/SlackValidationException.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index caa22e6..31b6d4e 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.api;
 
+import com.n1netails.n1netails.slack.exception.SlackApiExceptionWrapper;
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackMessage;
@@ -57,11 +58,13 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
             ChatPostMessageResponse response = methods.chatPostMessage(requestBuilder.build());
 
             if (!response.isOk()) {
-                throw new SlackClientException("Slack API error: " + response.getError());
+                throw new SlackApiExceptionWrapper(response.getError());
             }
 
-        } catch (IOException | SlackApiException e) {
-            throw new SlackClientException("Failed to send Slack message to channel: " + slackMessage.getChannel(), e);
+        } catch (IOException e) {
+            throw new SlackClientException("Network error while calling Slack API", e);
+        } catch (SlackApiException e) {
+            throw new SlackClientException("Slack SDK failure" + slackMessage.getChannel(), e);
         }
     }
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
index 1e9bebd..6b96f3c 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
@@ -38,7 +38,7 @@ public SlackClient.Builder token(String token) {
         @Override
         public SlackClient build() throws SlackClientException {
             if (this.token == null || this.token.isBlank())
-                throw new SlackClientException("token must be provided");
+                throw new SlackClientException("Token must be provided");
 
             return new SlackClientImpl(this);
         }
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
new file mode 100644
index 0000000..249a358
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
@@ -0,0 +1,14 @@
+package com.n1netails.n1netails.slack.exception;
+
+public class SlackApiExceptionWrapper extends SlackClientException {
+    private final String slackError;
+
+    public SlackApiExceptionWrapper(String slackError) {
+        super("Slack API error: " + slackError);
+        this.slackError = slackError;
+    }
+
+    public String getSlackError() {
+        return slackError;
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java
new file mode 100644
index 0000000..5baaae9
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java
@@ -0,0 +1,7 @@
+package com.n1netails.n1netails.slack.exception;
+
+public class SlackTransportException extends SlackClientException {
+    public SlackTransportException(String message) {
+        super(message);
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackValidationException.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackValidationException.java
new file mode 100644
index 0000000..671c5a8
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackValidationException.java
@@ -0,0 +1,7 @@
+package com.n1netails.n1netails.slack.exception;
+
+public class SlackValidationException extends SlackClientException {
+    public SlackValidationException(String message) {
+        super(message);
+    }
+}

From 4bcc3d1b86f8a78c7c3d88524245c4441ba5af61 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 21:16:49 +0100
Subject: [PATCH 11/37] Graceful fallback for unsupported or invalid media

---
 .../slack/fallback/SlackFallbackHandler.java  | 26 ++++++++++
 .../n1netails/slack/model/SlackMessage.java   | 50 +++++++++++++++----
 .../slack/model/blocks/FallbackBlock.java     | 20 ++++++++
 .../slack/model/blocks/GifBlock.java          | 11 ++--
 .../slack/model/blocks/ImageBlock.java        |  3 +-
 .../slack/model/blocks/TextBlock.java         |  2 +
 .../slack/validation/SlackValidator.java      |  7 +++
 .../slack/validation/SlackValidators.java     | 34 +++++++++++++
 .../validation/impl/GifBlockValidator.java    | 18 +++++++
 .../validation/impl/ImageBlockValidator.java  | 18 +++++++
 .../validation/impl/TextBlockValidator.java   | 15 ++++++
 11 files changed, 188 insertions(+), 16 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java b/src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java
new file mode 100644
index 0000000..da8d9bf
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java
@@ -0,0 +1,26 @@
+package com.n1netails.n1netails.slack.fallback;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.blocks.FallbackBlock;
+import com.n1netails.n1netails.slack.model.blocks.GifBlock;
+import com.n1netails.n1netails.slack.model.blocks.ImageBlock;
+import com.n1netails.n1netails.slack.model.blocks.TextBlock;
+
+public class SlackFallbackHandler {
+    public static SlackBlock handle(SlackBlock block, Exception e) {
+
+        if (block instanceof ImageBlock img) {
+            return new FallbackBlock("Image could not be displayed: " + img.getAltText());
+        }
+
+        if (block instanceof GifBlock gif) {
+            return new FallbackBlock("GIF could not be displayed: " + gif.getAltText());
+        }
+
+        if (block instanceof TextBlock txt) {
+            return new FallbackBlock("Text could not be displayed");
+        }
+
+        return new FallbackBlock("Unsupported content");
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 05d82a0..05c16b5 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -1,5 +1,8 @@
 package com.n1netails.n1netails.slack.model;
 
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.fallback.SlackFallbackHandler;
+import com.n1netails.n1netails.slack.validation.SlackValidators;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
 import lombok.Setter;
@@ -47,32 +50,59 @@ public Builder text(String text) {
             return this;
         }
 
-        public Builder addBlock(SlackBlock block) {
+        public Builder addBlock(SlackBlock block) throws SlackValidationException {
+            if (!rawBlocks.isEmpty()) {
+                throw new SlackValidationException(
+                        "Cannot add SlackBlock when rawBlocks are already present"
+                );
+            }
             this.blocks.add(block);
             return this;
         }
 
-        public Builder addRawBlock(LayoutBlock block) {
+        public Builder addRawBlock(LayoutBlock block) throws SlackValidationException {
+            if (!blocks.isEmpty()) {
+                throw new SlackValidationException(
+                        "Cannot add rawBlock when SlackBlocks are already present"
+                );
+            }
             this.rawBlocks.add(block);
             return this;
         }
 
-        public SlackMessage build() {
+        public SlackMessage build() throws SlackValidationException {
             if (channel == null || channel.isBlank()) {
-                throw new IllegalStateException("channel is required");
+                throw new SlackValidationException("channel is required");
             }
 
-            boolean hasTextOrBlocks = (text != null && !text.isBlank())
-                    || (!blocks.isEmpty())
-                    || (!rawBlocks.isEmpty());
+            boolean hasContent = (text != null && !text.isBlank())
+                    || !blocks.isEmpty()
+                    || !rawBlocks.isEmpty();
 
-            if (!hasTextOrBlocks) {
-                throw new IllegalStateException("Either text, blocks, or rawBlocks must be provided");
+            if (!hasContent) {
+                throw new SlackValidationException(
+                        "Either text, blocks, or rawBlocks must be provided"
+                );
             }
 
             if (!blocks.isEmpty() && !rawBlocks.isEmpty()) {
-                throw new IllegalStateException("Cannot mix SlackBlock and rawBlocks in the same message");
+                throw new SlackValidationException(
+                        "Cannot mix SlackBlock and rawBlocks in the same message"
+                );
             }
+            List<SlackBlock> processedBlocks = new ArrayList<>();
+
+            for (SlackBlock block : blocks) {
+                try {
+                    SlackValidators.validate(block);
+                    processedBlocks.add(block);
+                } catch (Exception e) {
+                    processedBlocks.add(SlackFallbackHandler.handle(block, e));
+                }
+            }
+
+            this.blocks.clear();
+            this.blocks.addAll(processedBlocks);
 
             return new SlackMessage(this);
         }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java
new file mode 100644
index 0000000..a483ba1
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java
@@ -0,0 +1,20 @@
+package com.n1netails.n1netails.slack.model.blocks;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.slack.api.model.block.LayoutBlock;
+import com.slack.api.model.block.composition.PlainTextObject;
+
+public class FallbackBlock implements SlackBlock {
+
+    private final String text;
+
+    public FallbackBlock(String text) {
+        this.text = text;
+    }
+    @Override
+    public LayoutBlock toLayoutBlock() {
+        return com.slack.api.model.block.SectionBlock.builder()
+                .text(new PlainTextObject(text, false))
+                .build();
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
index ba55585..15f7398 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
@@ -2,14 +2,15 @@
 
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
-import com.slack.api.model.block.composition.PlainTextObject;
+import lombok.Getter;
 
+@Getter
 public class GifBlock implements SlackBlock {
-    private final String imageUrl;
+    private final String gifUrl;
     private final String altText;
 
-    public GifBlock(String imageUrl, String altText) {
-        this.imageUrl = imageUrl;
+    public GifBlock(String gifUrl, String altText) {
+        this.gifUrl = gifUrl;
         this.altText = altText;
     }
 
@@ -19,7 +20,7 @@ public LayoutBlock toLayoutBlock() {
         return
                 com.slack.api.model.block.ImageBlock.builder()
                         .altText(altText)
-                        .imageUrl(imageUrl)
+                        .imageUrl(gifUrl)
                         .build()
                 ;
     }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
index 1a4141c..2c9cff1 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
@@ -4,9 +4,10 @@
 import com.slack.api.model.block.Blocks;
 import com.slack.api.model.block.LayoutBlock;
 import com.slack.api.model.block.composition.BlockCompositions;
+import lombok.Getter;
 
-import java.util.List;
 
+@Getter
 public class ImageBlock implements SlackBlock {
     private final String imageUrl;
     private final String altText;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
index 2109046..95f3b94 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
@@ -3,7 +3,9 @@
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
 import com.slack.api.model.block.composition.PlainTextObject;
+import lombok.Getter;
 
+@Getter
 public class TextBlock implements SlackBlock {
     private final String text;
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java
new file mode 100644
index 0000000..d5b9091
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java
@@ -0,0 +1,7 @@
+package com.n1netails.n1netails.slack.validation;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+
+public interface SlackValidator<T> {
+    void validate(T target) throws SlackValidationException;
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java
new file mode 100644
index 0000000..d52fe30
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java
@@ -0,0 +1,34 @@
+package com.n1netails.n1netails.slack.validation;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.blocks.GifBlock;
+import com.n1netails.n1netails.slack.model.blocks.ImageBlock;
+import com.n1netails.n1netails.slack.model.blocks.TextBlock;
+import com.n1netails.n1netails.slack.validation.impl.GifBlockValidator;
+import com.n1netails.n1netails.slack.validation.impl.ImageBlockValidator;
+import com.n1netails.n1netails.slack.validation.impl.TextBlockValidator;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class SlackValidators {
+    private static final Map<Class<?>, SlackValidator<?>> VALIDATORS = new HashMap<>();
+
+    static {
+        VALIDATORS.put(ImageBlock.class, new ImageBlockValidator());
+        VALIDATORS.put(GifBlock.class, new GifBlockValidator());
+        VALIDATORS.put(TextBlock.class, new TextBlockValidator());
+    }
+
+    @SuppressWarnings("unchecked")
+    public static <T> void validate(T target) throws SlackValidationException {
+        if (target == null) return;
+
+        SlackValidator<T> validator =
+                (SlackValidator<T>) VALIDATORS.get(target.getClass());
+
+        if (validator != null) {
+            validator.validate(target);
+        }
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java
new file mode 100644
index 0000000..18e9f5b
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java
@@ -0,0 +1,18 @@
+package com.n1netails.n1netails.slack.validation.impl;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.blocks.GifBlock;
+import com.n1netails.n1netails.slack.validation.SlackValidator;
+
+public class GifBlockValidator implements SlackValidator<GifBlock> {
+    @Override
+    public void validate(GifBlock target) throws SlackValidationException {
+        if (target.getGifUrl() == null || target.getGifUrl().isBlank()) {
+            throw new SlackValidationException("Gif URL cannot be empty");
+        }
+
+        if (target.getAltText() == null || target.getAltText().isBlank()) {
+            throw new SlackValidationException("altText is required for accessibility");
+        }
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java
new file mode 100644
index 0000000..2dacdd3
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java
@@ -0,0 +1,18 @@
+package com.n1netails.n1netails.slack.validation.impl;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.blocks.ImageBlock;
+import com.n1netails.n1netails.slack.validation.SlackValidator;
+
+public class ImageBlockValidator implements SlackValidator<ImageBlock> {
+    @Override
+    public void validate(ImageBlock target) throws SlackValidationException {
+        if (target.getImageUrl() == null || target.getImageUrl().isBlank()) {
+            throw new SlackValidationException("Image URL cannot be empty");
+        }
+
+        if (target.getAltText() == null || target.getAltText().isBlank()) {
+            throw new SlackValidationException("altText is required for accessibility");
+        }
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
new file mode 100644
index 0000000..4c03936
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
@@ -0,0 +1,15 @@
+package com.n1netails.n1netails.slack.validation.impl;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.blocks.TextBlock;
+import com.n1netails.n1netails.slack.validation.SlackValidator;
+
+public class TextBlockValidator implements SlackValidator<TextBlock> {
+    @Override
+    public void validate(TextBlock target) throws SlackValidationException {
+        if (target.getText() == null || target.getText().isBlank()) {
+            throw new SlackValidationException("Text cannot be empty");
+        }
+
+    }
+}

From 58d1df4fd5cd4325e9d193569e2da68aee1689fa Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 21:23:02 +0100
Subject: [PATCH 12/37] change to RuntimeException

---
 .../n1netails/slack/exception/SlackClientException.java         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackClientException.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackClientException.java
index 56a103b..3906188 100644
--- a/src/main/java/com/n1netails/n1netails/slack/exception/SlackClientException.java
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackClientException.java
@@ -4,7 +4,7 @@
  * Slack Client Exception
  * @author shahid foy
  */
-public class SlackClientException extends Exception {
+public class SlackClientException extends RuntimeException {
 
     /**
      * Slack Client Exception Constructor

From fdb99f33141d81871dfcb4c776362d36ef2509f0 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 21:29:23 +0100
Subject: [PATCH 13/37] Correct Exception handling

---
 .../com/n1netails/n1netails/slack/api/BotService.java    | 9 ++++++---
 .../slack/exception/SlackApiExceptionWrapper.java        | 6 ------
 .../slack/exception/SlackTransportException.java         | 4 ++++
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 31b6d4e..693644b 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -2,6 +2,8 @@
 
 import com.n1netails.n1netails.slack.exception.SlackApiExceptionWrapper;
 import com.n1netails.n1netails.slack.exception.SlackClientException;
+import com.n1netails.n1netails.slack.exception.SlackTransportException;
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackMessage;
 import com.slack.api.Slack;
@@ -40,6 +42,7 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
                     ChatPostMessageRequest.builder()
                             .channel(slackMessage.getChannel())
                             .text(slackMessage.getText());
+
             List<LayoutBlock> finalBlocks;
             if (slackMessage.getRawBlocks() != null && !slackMessage.getRawBlocks().isEmpty()) {
                 finalBlocks = slackMessage.getRawBlocks();
@@ -62,15 +65,15 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
             }
 
         } catch (IOException e) {
-            throw new SlackClientException("Network error while calling Slack API", e);
+            throw new SlackTransportException("Network error while calling Slack API", e);
         } catch (SlackApiException e) {
-            throw new SlackClientException("Slack SDK failure" + slackMessage.getChannel(), e);
+            throw new SlackTransportException("Slack SDK failure" + slackMessage.getChannel(), e);
         }
     }
 
     private void validateSlackMessage(SlackMessage slackMessage) throws SlackClientException {
         if (slackMessage == null) {
-            throw new SlackClientException("slackMessage cannot be null");
+            throw new SlackValidationException("slackMessage cannot be null");
         }
 
     }
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
index 249a358..84dffdc 100644
--- a/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
@@ -1,14 +1,8 @@
 package com.n1netails.n1netails.slack.exception;
 
 public class SlackApiExceptionWrapper extends SlackClientException {
-    private final String slackError;
-
     public SlackApiExceptionWrapper(String slackError) {
         super("Slack API error: " + slackError);
-        this.slackError = slackError;
-    }
 
-    public String getSlackError() {
-        return slackError;
     }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java
index 5baaae9..642f6e2 100644
--- a/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackTransportException.java
@@ -4,4 +4,8 @@ public class SlackTransportException extends SlackClientException {
     public SlackTransportException(String message) {
         super(message);
     }
+
+    public SlackTransportException(String message, Throwable cause) {
+        super(message, cause);
+    }
 }

From db85abc62a9e3b92a80bc89fa43c7856711538c8 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 17 Feb 2026 21:29:43 +0100
Subject: [PATCH 14/37] bug in text validation

---
 .../com/n1netails/n1netails/slack/model/SlackMessage.java     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 05c16b5..b183406 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -76,8 +76,8 @@ public SlackMessage build() throws SlackValidationException {
             }
 
             boolean hasContent = (text != null && !text.isBlank())
-                    || !blocks.isEmpty()
-                    || !rawBlocks.isEmpty();
+                    && (!blocks.isEmpty()
+                    || !rawBlocks.isEmpty());
 
             if (!hasContent) {
                 throw new SlackValidationException(

From fde56f595837a58d593f08ff0cdeac5915723676 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Wed, 18 Feb 2026 13:35:40 +0100
Subject: [PATCH 15/37] refactoring BotService

---
 .../n1netails/slack/api/BotService.java       | 60 +++++++++++--------
 1 file changed, 35 insertions(+), 25 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 693644b..7cad471 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -38,43 +38,53 @@ public BotService(String token) {
     public void send(SlackMessage slackMessage) throws SlackClientException {
         validateSlackMessage(slackMessage);
         try {
-            ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder =
-                    ChatPostMessageRequest.builder()
-                            .channel(slackMessage.getChannel())
-                            .text(slackMessage.getText());
+            ChatPostMessageRequest request = buildRequest(slackMessage);
+            ChatPostMessageResponse response = executeRequest(request);
+            handleSlackResponse(response);
+        } catch (IOException e) {
+            throw new SlackTransportException("Network error while calling Slack API", e);
+        } catch (SlackApiException e) {
+            throw new SlackTransportException("Slack SDK failure" + slackMessage.getChannel(), e);
+        }
+    }
 
-            List<LayoutBlock> finalBlocks;
-            if (slackMessage.getRawBlocks() != null && !slackMessage.getRawBlocks().isEmpty()) {
-                finalBlocks = slackMessage.getRawBlocks();
+    private void handleSlackResponse(ChatPostMessageResponse response) throws SlackApiExceptionWrapper {
+        if (!response.isOk()) {
+            throw new SlackApiExceptionWrapper(response.getError());
+        }
+    }
 
-            } else if (slackMessage.getBlocks() != null && !slackMessage.getBlocks().isEmpty()) {
-                finalBlocks = slackMessage.getBlocks().stream()
-                        .map(SlackBlock::toLayoutBlock)
-                        .toList();
-            } else
-                finalBlocks = null;
+    private ChatPostMessageResponse executeRequest(ChatPostMessageRequest request) throws SlackApiException, IOException {
+        return methods.chatPostMessage(request);
+    }
 
-            if (finalBlocks != null && !finalBlocks.isEmpty()) {
-                requestBuilder.blocks(finalBlocks);
-            }
+    private ChatPostMessageRequest buildRequest(SlackMessage slackMessage) {
+        ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder =
+                ChatPostMessageRequest.builder()
+                        .channel(slackMessage.getChannel())
+                        .text(slackMessage.getText());
 
-            ChatPostMessageResponse response = methods.chatPostMessage(requestBuilder.build());
+        List<LayoutBlock> blocks = resolveBlocks(slackMessage);
+        if ((blocks != null && !blocks.isEmpty()))
+            requestBuilder.blocks(blocks);
+        return requestBuilder.build();
+    }
 
-            if (!response.isOk()) {
-                throw new SlackApiExceptionWrapper(response.getError());
-            }
+    private List<LayoutBlock> resolveBlocks(SlackMessage slackMessage) {
+        if (slackMessage.getRawBlocks() != null && !slackMessage.getRawBlocks().isEmpty())
+            return slackMessage.getRawBlocks();
 
-        } catch (IOException e) {
-            throw new SlackTransportException("Network error while calling Slack API", e);
-        } catch (SlackApiException e) {
-            throw new SlackTransportException("Slack SDK failure" + slackMessage.getChannel(), e);
+        if (slackMessage.getBlocks() != null && !slackMessage.getBlocks().isEmpty()) {
+            return slackMessage.getBlocks().stream()
+                    .map(SlackBlock::toLayoutBlock)
+                    .toList();
         }
+        return null;
     }
 
     private void validateSlackMessage(SlackMessage slackMessage) throws SlackClientException {
         if (slackMessage == null) {
             throw new SlackValidationException("slackMessage cannot be null");
         }
-
     }
 }

From 0a7b3ca973fbca14eb7ac9789c4e63b002b8c7f0 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Wed, 18 Feb 2026 13:43:52 +0100
Subject: [PATCH 16/37] Builder for SlackMessage refactoring

---
 .../n1netails/slack/model/SlackMessage.java   | 28 +++++++++++++------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index b183406..2192eb5 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -30,6 +30,13 @@ private SlackMessage(Builder builder) {
         this.rawBlocks = List.copyOf(builder.rawBlocks);
     }
 
+    private SlackMessage(String channel, String text, List<SlackBlock> blocks, List<LayoutBlock> rawBlocks) {
+        this.channel = channel;
+        this.text = text;
+        this.blocks = blocks;
+        this.rawBlocks = rawBlocks;
+    }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -76,8 +83,9 @@ public SlackMessage build() throws SlackValidationException {
             }
 
             boolean hasContent = (text != null && !text.isBlank())
-                    && (!blocks.isEmpty()
-                    || !rawBlocks.isEmpty());
+                    || !blocks.isEmpty()
+                    || !rawBlocks.isEmpty();
+
 
             if (!hasContent) {
                 throw new SlackValidationException(
@@ -90,8 +98,16 @@ public SlackMessage build() throws SlackValidationException {
                         "Cannot mix SlackBlock and rawBlocks in the same message"
                 );
             }
-            List<SlackBlock> processedBlocks = new ArrayList<>();
+            List<SlackBlock> processedBlocks = processBlocks(blocks);
+
+            this.blocks.clear();
+            this.blocks.addAll(processedBlocks);
 
+            return new SlackMessage(channel, text, processedBlocks, List.copyOf(rawBlocks));
+        }
+
+        private List<SlackBlock> processBlocks(List<SlackBlock> blocks) {
+            List<SlackBlock> processedBlocks = new ArrayList<>();
             for (SlackBlock block : blocks) {
                 try {
                     SlackValidators.validate(block);
@@ -100,11 +116,7 @@ public SlackMessage build() throws SlackValidationException {
                     processedBlocks.add(SlackFallbackHandler.handle(block, e));
                 }
             }
-
-            this.blocks.clear();
-            this.blocks.addAll(processedBlocks);
-
-            return new SlackMessage(this);
+            return List.copyOf(processedBlocks);
         }
 
     }

From d52a4838f82fdf9f0c9e2b672501cf6a95e51543 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Wed, 18 Feb 2026 13:47:45 +0100
Subject: [PATCH 17/37] deleted double functionality

---
 .../com/n1netails/n1netails/slack/model/SlackMessage.java  | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 2192eb5..4d48418 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -100,10 +100,7 @@ public SlackMessage build() throws SlackValidationException {
             }
             List<SlackBlock> processedBlocks = processBlocks(blocks);
 
-            this.blocks.clear();
-            this.blocks.addAll(processedBlocks);
-
-            return new SlackMessage(channel, text, processedBlocks, List.copyOf(rawBlocks));
+            return new SlackMessage(channel, text, List.copyOf(processedBlocks), List.copyOf(rawBlocks));
         }
 
         private List<SlackBlock> processBlocks(List<SlackBlock> blocks) {
@@ -116,7 +113,7 @@ private List<SlackBlock> processBlocks(List<SlackBlock> blocks) {
                     processedBlocks.add(SlackFallbackHandler.handle(block, e));
                 }
             }
-            return List.copyOf(processedBlocks);
+            return processedBlocks;
         }
 
     }

From d45dd7df3369e09ef24cd4d6477d962a2194546f Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Sun, 22 Feb 2026 10:27:58 +0100
Subject: [PATCH 18/37] remove validation behaviour from builder

---
 .../n1netails/slack/model/SlackMessage.java   | 22 +------------------
 1 file changed, 1 insertion(+), 21 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 4d48418..2b09543 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -30,12 +30,6 @@ private SlackMessage(Builder builder) {
         this.rawBlocks = List.copyOf(builder.rawBlocks);
     }
 
-    private SlackMessage(String channel, String text, List<SlackBlock> blocks, List<LayoutBlock> rawBlocks) {
-        this.channel = channel;
-        this.text = text;
-        this.blocks = blocks;
-        this.rawBlocks = rawBlocks;
-    }
 
     public static Builder builder() {
         return new Builder();
@@ -98,22 +92,8 @@ public SlackMessage build() throws SlackValidationException {
                         "Cannot mix SlackBlock and rawBlocks in the same message"
                 );
             }
-            List<SlackBlock> processedBlocks = processBlocks(blocks);
-
-            return new SlackMessage(channel, text, List.copyOf(processedBlocks), List.copyOf(rawBlocks));
-        }
 
-        private List<SlackBlock> processBlocks(List<SlackBlock> blocks) {
-            List<SlackBlock> processedBlocks = new ArrayList<>();
-            for (SlackBlock block : blocks) {
-                try {
-                    SlackValidators.validate(block);
-                    processedBlocks.add(block);
-                } catch (Exception e) {
-                    processedBlocks.add(SlackFallbackHandler.handle(block, e));
-                }
-            }
-            return processedBlocks;
+            return new SlackMessage(this);
         }
 
     }

From c33962271c116ec084cb0769a552f369f3838209 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Sun, 22 Feb 2026 10:28:44 +0100
Subject: [PATCH 19/37] place validation behaviour into Service

---
 .../n1netails/slack/api/BotService.java       | 56 +++++++++++++++----
 .../validation/impl/TextBlockValidator.java   |  1 -
 2 files changed, 44 insertions(+), 13 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 7cad471..71fddf0 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -4,8 +4,10 @@
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.exception.SlackTransportException;
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.fallback.SlackFallbackHandler;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackMessage;
+import com.n1netails.n1netails.slack.validation.SlackValidators;
 import com.slack.api.Slack;
 import com.slack.api.methods.MethodsClient;
 import com.slack.api.methods.SlackApiException;
@@ -16,6 +18,7 @@
 import lombok.Setter;
 
 import java.io.IOException;
+import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -40,7 +43,9 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
         try {
             ChatPostMessageRequest request = buildRequest(slackMessage);
             ChatPostMessageResponse response = executeRequest(request);
-            handleSlackResponse(response);
+            if (!response.isOk()) {
+                fallbackToText(slackMessage, response);
+            }
         } catch (IOException e) {
             throw new SlackTransportException("Network error while calling Slack API", e);
         } catch (SlackApiException e) {
@@ -48,12 +53,27 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
         }
     }
 
-    private void handleSlackResponse(ChatPostMessageResponse response) throws SlackApiExceptionWrapper {
-        if (!response.isOk()) {
-            throw new SlackApiExceptionWrapper(response.getError());
+    private void fallbackToText(SlackMessage message, ChatPostMessageResponse originalResponse) {
+        try {
+            ChatPostMessageRequest fallbackRequest =
+                    ChatPostMessageRequest.builder()
+                            .channel(message.getChannel())
+                            .text(message.getText())
+                            .build();
+
+            ChatPostMessageResponse fallbackResponse =
+                    executeRequest(fallbackRequest);
+
+            if (!fallbackResponse.isOk()) {
+                throw new SlackApiExceptionWrapper(originalResponse.getError());
+            }
+
+        } catch (Exception e) {
+            throw new SlackApiExceptionWrapper(originalResponse.getError());
         }
     }
 
+
     private ChatPostMessageResponse executeRequest(ChatPostMessageRequest request) throws SlackApiException, IOException {
         return methods.chatPostMessage(request);
     }
@@ -70,16 +90,28 @@ private ChatPostMessageRequest buildRequest(SlackMessage slackMessage) {
         return requestBuilder.build();
     }
 
-    private List<LayoutBlock> resolveBlocks(SlackMessage slackMessage) {
-        if (slackMessage.getRawBlocks() != null && !slackMessage.getRawBlocks().isEmpty())
-            return slackMessage.getRawBlocks();
+    private List<LayoutBlock> resolveBlocks(SlackMessage message) {
+        if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
+            return message.getRawBlocks();
+        }
 
-        if (slackMessage.getBlocks() != null && !slackMessage.getBlocks().isEmpty()) {
-            return slackMessage.getBlocks().stream()
-                    .map(SlackBlock::toLayoutBlock)
-                    .toList();
+        if (message.getBlocks() == null || message.getBlocks().isEmpty()) {
+            return null;
         }
-        return null;
+
+        List<LayoutBlock> result = new ArrayList<>();
+
+        for (SlackBlock block : message.getBlocks()) {
+            try {
+                SlackValidators.validate(block);
+                result.add(block.toLayoutBlock());
+            } catch (Exception e) {
+                SlackBlock fallback = SlackFallbackHandler.handle(block, e);
+                result.add(fallback.toLayoutBlock());
+            }
+        }
+
+        return result;
     }
 
     private void validateSlackMessage(SlackMessage slackMessage) throws SlackClientException {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
index 4c03936..3161b5d 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
@@ -10,6 +10,5 @@ public void validate(TextBlock target) throws SlackValidationException {
         if (target.getText() == null || target.getText().isBlank()) {
             throw new SlackValidationException("Text cannot be empty");
         }
-
     }
 }

From fbd74b0d82878f6beaa3625d8cdc7ad57fdce855 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Sun, 22 Feb 2026 14:52:51 +0100
Subject: [PATCH 20/37] restructure to keep it simple

---
 .../n1netails/slack/api/BotService.java       | 76 +++++--------------
 .../slack/exception/SlackErrorMapper.java     | 65 ++++++++++++++++
 .../slack/fallback/SlackFallbackHandler.java  | 26 -------
 .../n1netails/slack/model/SlackMessage.java   |  3 -
 .../slack/processing/SlackBlockProcessor.java | 63 +++++++++++++++
 ...idators.java => BasicSlackValidators.java} | 25 +++---
 6 files changed, 155 insertions(+), 103 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
 delete mode 100644 src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java
 rename src/main/java/com/n1netails/n1netails/slack/validation/{SlackValidators.java => BasicSlackValidators.java} (50%)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 71fddf0..00616ad 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -1,24 +1,19 @@
 package com.n1netails.n1netails.slack.api;
 
-import com.n1netails.n1netails.slack.exception.SlackApiExceptionWrapper;
+import com.n1netails.n1netails.slack.exception.SlackErrorMapper;
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.exception.SlackTransportException;
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.fallback.SlackFallbackHandler;
-import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.validation.SlackValidators;
+import com.n1netails.n1netails.slack.processing.SlackBlockProcessor;
 import com.slack.api.Slack;
 import com.slack.api.methods.MethodsClient;
 import com.slack.api.methods.SlackApiException;
 import com.slack.api.methods.request.chat.ChatPostMessageRequest;
 import com.slack.api.methods.response.chat.ChatPostMessageResponse;
 import com.slack.api.model.block.LayoutBlock;
-import lombok.Getter;
-import lombok.Setter;
 
 import java.io.IOException;
-import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -28,6 +23,7 @@
  */
 class BotService {
     private final MethodsClient methods;
+    private final SlackBlockProcessor blockProcessor;
 
     /**
      * Bot Service Constructor
@@ -36,87 +32,51 @@ class BotService {
      */
     public BotService(String token) {
         this.methods = Slack.getInstance().methods(token);
+        this.blockProcessor = new SlackBlockProcessor();
+
     }
 
     public void send(SlackMessage slackMessage) throws SlackClientException {
-        validateSlackMessage(slackMessage);
+        validateBasic(slackMessage);
         try {
             ChatPostMessageRequest request = buildRequest(slackMessage);
-            ChatPostMessageResponse response = executeRequest(request);
+            ChatPostMessageResponse response = methods.chatPostMessage(request);
             if (!response.isOk()) {
-                fallbackToText(slackMessage, response);
+                throw SlackErrorMapper.map(response);
             }
         } catch (IOException e) {
             throw new SlackTransportException("Network error while calling Slack API", e);
         } catch (SlackApiException e) {
-            throw new SlackTransportException("Slack SDK failure" + slackMessage.getChannel(), e);
+            throw new SlackTransportException("Slack SDK failure for channel: " + slackMessage.getChannel(), e);
         }
     }
 
-    private void fallbackToText(SlackMessage message, ChatPostMessageResponse originalResponse) {
-        try {
-            ChatPostMessageRequest fallbackRequest =
-                    ChatPostMessageRequest.builder()
-                            .channel(message.getChannel())
-                            .text(message.getText())
-                            .build();
 
-            ChatPostMessageResponse fallbackResponse =
-                    executeRequest(fallbackRequest);
+    private void validateBasic(SlackMessage message) throws SlackValidationException {
+        if (message == null) {
+            throw new SlackValidationException("SlackMessage cannot be null");
+        }
 
-            if (!fallbackResponse.isOk()) {
-                throw new SlackApiExceptionWrapper(originalResponse.getError());
-            }
+        if ((message.getText() == null || message.getText().isBlank()) &&
+                (message.getBlocks() == null || message.getBlocks().isEmpty()) &&
+                (message.getRawBlocks() == null || message.getRawBlocks().isEmpty())) {
 
-        } catch (Exception e) {
-            throw new SlackApiExceptionWrapper(originalResponse.getError());
+            throw new SlackValidationException("Message must contain text or blocks");
         }
     }
 
 
-    private ChatPostMessageResponse executeRequest(ChatPostMessageRequest request) throws SlackApiException, IOException {
-        return methods.chatPostMessage(request);
-    }
-
     private ChatPostMessageRequest buildRequest(SlackMessage slackMessage) {
         ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder =
                 ChatPostMessageRequest.builder()
                         .channel(slackMessage.getChannel())
                         .text(slackMessage.getText());
 
-        List<LayoutBlock> blocks = resolveBlocks(slackMessage);
+        List<LayoutBlock> blocks = blockProcessor.process(slackMessage);
         if ((blocks != null && !blocks.isEmpty()))
             requestBuilder.blocks(blocks);
         return requestBuilder.build();
     }
 
-    private List<LayoutBlock> resolveBlocks(SlackMessage message) {
-        if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
-            return message.getRawBlocks();
-        }
-
-        if (message.getBlocks() == null || message.getBlocks().isEmpty()) {
-            return null;
-        }
 
-        List<LayoutBlock> result = new ArrayList<>();
-
-        for (SlackBlock block : message.getBlocks()) {
-            try {
-                SlackValidators.validate(block);
-                result.add(block.toLayoutBlock());
-            } catch (Exception e) {
-                SlackBlock fallback = SlackFallbackHandler.handle(block, e);
-                result.add(fallback.toLayoutBlock());
-            }
-        }
-
-        return result;
-    }
-
-    private void validateSlackMessage(SlackMessage slackMessage) throws SlackClientException {
-        if (slackMessage == null) {
-            throw new SlackValidationException("slackMessage cannot be null");
-        }
-    }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
new file mode 100644
index 0000000..52f1de5
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
@@ -0,0 +1,65 @@
+package com.n1netails.n1netails.slack.exception;
+
+import com.slack.api.methods.response.chat.ChatPostMessageResponse;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class SlackErrorMapper {
+
+    public static SlackValidationException map(ChatPostMessageResponse response) {
+        if (response.getErrors() == null || response.getErrors().isEmpty()) {
+            return new SlackValidationException(response.getError());
+        }
+
+        List<String> formattedErrors = new ArrayList<>();
+
+        for (String error : response.getErrors()) {
+            formattedErrors.add(format(error));
+        }
+
+        return new SlackValidationException(
+                "Slack API validation failed:\n - " + String.join("\n - ", formattedErrors)
+        );
+    }
+
+    private static String format(String rawError) {
+        try {
+            String message = rawError;
+            int pointerStart = rawError.indexOf("[json-pointer:");
+
+            if (pointerStart > -1) {
+                message = rawError.substring(0, pointerStart).trim();
+
+                String pointer = rawError.substring(pointerStart)
+                        .replace("[json-pointer:", "")
+                        .replace("]", "");
+
+                return mapPointer(pointer, message);
+            }
+
+            return message;
+
+        } catch (Exception e) {
+            return rawError; // fallback
+        }
+    }
+
+    private static String mapPointer(String pointer, String message) {
+        String[] parts = pointer.split("/");
+
+        if (parts.length >= 4 && "blocks".equals(parts[1])) {
+            int index = Integer.parseInt(parts[2]);
+            String field = parts[3];
+
+            return String.format(
+                    "Block[%d].%s: %s",
+                    index,
+                    field,
+                    message
+            );
+        }
+
+        return pointer + ": " + message;
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java b/src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java
deleted file mode 100644
index da8d9bf..0000000
--- a/src/main/java/com/n1netails/n1netails/slack/fallback/SlackFallbackHandler.java
+++ /dev/null
@@ -1,26 +0,0 @@
-package com.n1netails.n1netails.slack.fallback;
-
-import com.n1netails.n1netails.slack.model.SlackBlock;
-import com.n1netails.n1netails.slack.model.blocks.FallbackBlock;
-import com.n1netails.n1netails.slack.model.blocks.GifBlock;
-import com.n1netails.n1netails.slack.model.blocks.ImageBlock;
-import com.n1netails.n1netails.slack.model.blocks.TextBlock;
-
-public class SlackFallbackHandler {
-    public static SlackBlock handle(SlackBlock block, Exception e) {
-
-        if (block instanceof ImageBlock img) {
-            return new FallbackBlock("Image could not be displayed: " + img.getAltText());
-        }
-
-        if (block instanceof GifBlock gif) {
-            return new FallbackBlock("GIF could not be displayed: " + gif.getAltText());
-        }
-
-        if (block instanceof TextBlock txt) {
-            return new FallbackBlock("Text could not be displayed");
-        }
-
-        return new FallbackBlock("Unsupported content");
-    }
-}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 2b09543..825e81c 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -1,11 +1,8 @@
 package com.n1netails.n1netails.slack.model;
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.fallback.SlackFallbackHandler;
-import com.n1netails.n1netails.slack.validation.SlackValidators;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
-import lombok.Setter;
 
 import java.util.ArrayList;
 import java.util.List;
diff --git a/src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java b/src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java
new file mode 100644
index 0000000..723f511
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java
@@ -0,0 +1,63 @@
+package com.n1netails.n1netails.slack.processing;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackMessage;
+import com.n1netails.n1netails.slack.validation.BasicSlackValidators;
+import com.slack.api.model.block.LayoutBlock;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class SlackBlockProcessor {
+
+    private final BasicSlackValidators basicSlackValidators;
+
+    public SlackBlockProcessor() {
+        this.basicSlackValidators = new BasicSlackValidators();
+    }
+
+    public List<LayoutBlock> process(SlackMessage message) {
+        if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
+            return message.getRawBlocks();
+        }
+
+        if (message.getBlocks() == null || message.getBlocks().isEmpty()) {
+            return null;
+        }
+
+        List<LayoutBlock> result = new ArrayList<>();
+        List<String> errors = new ArrayList<>();
+
+        int index = 0;
+
+        for (SlackBlock block : message.getBlocks()) {
+            try {
+                basicSlackValidators.validate(block);
+                result.add(block.toLayoutBlock());
+            } catch (SlackValidationException e) {
+                errors.add(formatError(index, block, e));
+            }
+            index++;
+        }
+
+        if (!errors.isEmpty()) {
+            throw new SlackValidationException(buildErrorMessage(errors));
+        }
+
+        return result;
+    }
+
+    private String formatError(int index, SlackBlock block, Exception e) {
+        return String.format(
+                "Block[%d] (%s): %s",
+                index,
+                block.getClass().getSimpleName(),
+                e.getMessage()
+        );
+    }
+
+    private String buildErrorMessage(List<String> errors) {
+        return "Slack message validation failed:\n - " + String.join("\n - ", errors);
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
similarity index 50%
rename from src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java
rename to src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index d52fe30..c0c2c81 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -11,24 +11,17 @@
 import java.util.HashMap;
 import java.util.Map;
 
-public class SlackValidators {
-    private static final Map<Class<?>, SlackValidator<?>> VALIDATORS = new HashMap<>();
+public class BasicSlackValidators {
+    private final Map<Class<?>, SlackValidator<?>> validators = new HashMap<>();
 
-    static {
-        VALIDATORS.put(ImageBlock.class, new ImageBlockValidator());
-        VALIDATORS.put(GifBlock.class, new GifBlockValidator());
-        VALIDATORS.put(TextBlock.class, new TextBlockValidator());
+    public BasicSlackValidators() {
+        validators.put(ImageBlock.class, new ImageBlockValidator());
+        validators.put(GifBlock.class, new GifBlockValidator());
+        validators.put(TextBlock.class, new TextBlockValidator());
     }
-
-    @SuppressWarnings("unchecked")
-    public static <T> void validate(T target) throws SlackValidationException {
+    public <T> void validate(T target) {
         if (target == null) return;
-
-        SlackValidator<T> validator =
-                (SlackValidator<T>) VALIDATORS.get(target.getClass());
-
-        if (validator != null) {
-            validator.validate(target);
-        }
+        SlackValidator<T> validator = (SlackValidator<T>) validators.get(target.getClass());
+        if (validator != null) validator.validate(target);
     }
 }

From e8eea5ade97f369eec350e60898eca450dac41f8 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 12:28:32 +0100
Subject: [PATCH 21/37] new block

---
 .../slack/model/block/ActionsBlock.java       | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
new file mode 100644
index 0000000..d6778eb
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
@@ -0,0 +1,30 @@
+package com.n1netails.n1netails.slack.model.block;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackElement;
+import com.slack.api.model.block.LayoutBlock;
+import lombok.Getter;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Getter
+public class ActionsBlock implements SlackBlock {
+
+    private final List<SlackElement> elements;
+
+    public ActionsBlock(List<SlackElement> elements) {
+        this.elements = elements;
+    }
+
+    @Override
+    public LayoutBlock toLayoutBlock() {
+        return com.slack.api.model.block.ActionsBlock.builder()
+                .elements(
+                        elements.stream()
+                                .map(SlackElement::toBlockElement)
+                                .toList()
+                )
+                .build();
+    }
+}

From 95c010001b850de2f52440b8c51d41cd557c77c5 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 12:29:00 +0100
Subject: [PATCH 22/37] first element for the ActionsBlock

---
 .../slack/model/actions_element/Button.java   | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java
new file mode 100644
index 0000000..92fedf1
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java
@@ -0,0 +1,32 @@
+package com.n1netails.n1netails.slack.model.actions_element;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.SlackElement;
+import com.slack.api.model.block.composition.PlainTextObject;
+import com.slack.api.model.block.element.BlockElement;
+import com.slack.api.model.block.element.ButtonElement;
+import lombok.Getter;
+
+@Getter
+public class Button implements SlackElement {
+    private final String text;
+    private final String actionId;
+    private final String url;
+
+    public Button(String text, String actionId, String url) {
+        this.text = text;
+        this.actionId = actionId;
+        this.url = url;
+    }
+
+    @Override
+    public BlockElement toBlockElement() {
+        return com.slack.api.model.block.element.ButtonElement.builder()
+                .text(com.slack.api.model.block.composition.PlainTextObject.builder()
+                        .text(text)
+                        .build())
+                .actionId(actionId)
+                .url(url)
+                .build();
+    }
+}

From d91ef66179b3bd9293ca4b3d83957d22d80461a7 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 12:29:41 +0100
Subject: [PATCH 23/37] validators

---
 .../validation/BasicSlackValidators.java      | 22 ++++++++++-----
 .../impl/block/ActionsBlockValidator.java     | 27 +++++++++++++++++++
 .../impl/element/ButtonElementValidator.java  | 21 +++++++++++++++
 3 files changed, 63 insertions(+), 7 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index c0c2c81..b01d5da 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -1,12 +1,13 @@
 package com.n1netails.n1netails.slack.validation;
 
-import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.blocks.GifBlock;
-import com.n1netails.n1netails.slack.model.blocks.ImageBlock;
-import com.n1netails.n1netails.slack.model.blocks.TextBlock;
-import com.n1netails.n1netails.slack.validation.impl.GifBlockValidator;
-import com.n1netails.n1netails.slack.validation.impl.ImageBlockValidator;
-import com.n1netails.n1netails.slack.validation.impl.TextBlockValidator;
+import com.n1netails.n1netails.slack.model.block.ActionsBlock;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
+import com.n1netails.n1netails.slack.model.block.ImageBlock;
+import com.n1netails.n1netails.slack.model.block.TextBlock;
+import com.n1netails.n1netails.slack.validation.impl.block.ActionsBlockValidator;
+import com.n1netails.n1netails.slack.validation.impl.block.GifBlockValidator;
+import com.n1netails.n1netails.slack.validation.impl.block.ImageBlockValidator;
+import com.n1netails.n1netails.slack.validation.impl.block.TextBlockValidator;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -14,11 +15,18 @@
 public class BasicSlackValidators {
     private final Map<Class<?>, SlackValidator<?>> validators = new HashMap<>();
 
+
     public BasicSlackValidators() {
+        init();
+    }
+
+    private void init() {
         validators.put(ImageBlock.class, new ImageBlockValidator());
         validators.put(GifBlock.class, new GifBlockValidator());
         validators.put(TextBlock.class, new TextBlockValidator());
+        validators.put(ActionsBlock.class, new ActionsBlockValidator(this));
     }
+
     public <T> void validate(T target) {
         if (target == null) return;
         SlackValidator<T> validator = (SlackValidator<T>) validators.get(target.getClass());
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
new file mode 100644
index 0000000..ed5a8d6
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
@@ -0,0 +1,27 @@
+package com.n1netails.n1netails.slack.validation.impl.block;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.SlackElement;
+import com.n1netails.n1netails.slack.model.block.ActionsBlock;
+import com.n1netails.n1netails.slack.validation.BasicSlackValidators;
+import com.n1netails.n1netails.slack.validation.SlackValidator;
+
+public class ActionsBlockValidator implements SlackValidator<ActionsBlock> {
+    private final BasicSlackValidators validators;
+
+    public ActionsBlockValidator(BasicSlackValidators validators) {
+        this.validators = validators;
+    }
+
+    @Override
+    public void validate(ActionsBlock target) throws SlackValidationException {
+        if (target.getElements() == null || target.getElements().isEmpty()) {
+            throw new SlackValidationException("ActionsBlock must contain at least one element");
+        }
+
+
+        for (SlackElement element : target.getElements()) {
+            validators.validate(element);
+        }
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
new file mode 100644
index 0000000..c641d5e
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
@@ -0,0 +1,21 @@
+package com.n1netails.n1netails.slack.validation.impl.element;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.actions_element.Button;
+import com.n1netails.n1netails.slack.validation.SlackValidator;
+
+public class ButtonElementValidator implements SlackValidator<Button> {
+    @Override
+    public void validate(Button target) throws SlackValidationException {
+        if (target.getText() == null || target.getText().isBlank()) {
+            throw new SlackValidationException("Button text is required");
+        }
+        if ((target.getActionId() == null || target.getActionId().isBlank()) &&
+                (target.getUrl() == null || target.getUrl().isBlank())) {
+            throw new SlackValidationException(
+                    "Button must have either actionId or url"
+            );
+        }
+
+    }
+}

From db345bb53f3c4ab68a72e980422e7af5d9330e5f Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 12:30:39 +0100
Subject: [PATCH 24/37] package renamed

---
 readme.md                                     |  6 ++----
 .../n1netails/slack/model/SlackElement.java   |  7 +++++++
 .../model/{blocks => block}/GifBlock.java     |  2 +-
 .../model/{blocks => block}/ImageBlock.java   |  4 +---
 .../model/{blocks => block}/TextBlock.java    |  2 +-
 .../slack/model/blocks/FallbackBlock.java     | 20 -------------------
 .../impl/{ => block}/GifBlockValidator.java   |  4 ++--
 .../impl/{ => block}/ImageBlockValidator.java |  4 ++--
 .../impl/{ => block}/TextBlockValidator.java  |  4 ++--
 9 files changed, 18 insertions(+), 35 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
 rename src/main/java/com/n1netails/n1netails/slack/model/{blocks => block}/GifBlock.java (92%)
 rename src/main/java/com/n1netails/n1netails/slack/model/{blocks => block}/ImageBlock.java (80%)
 rename src/main/java/com/n1netails/n1netails/slack/model/{blocks => block}/TextBlock.java (91%)
 delete mode 100644 src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java
 rename src/main/java/com/n1netails/n1netails/slack/validation/impl/{ => block}/GifBlockValidator.java (84%)
 rename src/main/java/com/n1netails/n1netails/slack/validation/impl/{ => block}/ImageBlockValidator.java (84%)
 rename src/main/java/com/n1netails/n1netails/slack/validation/impl/{ => block}/TextBlockValidator.java (79%)

diff --git a/readme.md b/readme.md
index 255d1c1..ecfbde9 100644
--- a/readme.md
+++ b/readme.md
@@ -51,11 +51,9 @@ Here's how to use the client to send a message, pics or gifs:
 
 ```java
 import com.n1netails.n1netails.slack.api.SlackClient;
-import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.api.BotService;
-import com.n1netails.n1netails.slack.model.blocks.GifBlock;
-import com.n1netails.n1netails.slack.model.blocks.TextBlock;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
+import com.n1netails.n1netails.slack.model.block.TextBlock;
 
 public class Example {
     public static void main(String[] args) {
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
new file mode 100644
index 0000000..1044e6c
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
@@ -0,0 +1,7 @@
+package com.n1netails.n1netails.slack.model;
+
+import com.slack.api.model.block.element.BlockElement;
+
+public interface SlackElement {
+    BlockElement toBlockElement();
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
similarity index 92%
rename from src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
rename to src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
index 15f7398..5b49647 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
@@ -1,4 +1,4 @@
-package com.n1netails.n1netails.slack.model.blocks;
+package com.n1netails.n1netails.slack.model.block;
 
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
similarity index 80%
rename from src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
rename to src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
index 2c9cff1..29fb499 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
@@ -1,9 +1,7 @@
-package com.n1netails.n1netails.slack.model.blocks;
+package com.n1netails.n1netails.slack.model.block;
 
 import com.n1netails.n1netails.slack.model.SlackBlock;
-import com.slack.api.model.block.Blocks;
 import com.slack.api.model.block.LayoutBlock;
-import com.slack.api.model.block.composition.BlockCompositions;
 import lombok.Getter;
 
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
similarity index 91%
rename from src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
rename to src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
index 95f3b94..ab4b743 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
@@ -1,4 +1,4 @@
-package com.n1netails.n1netails.slack.model.blocks;
+package com.n1netails.n1netails.slack.model.block;
 
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java
deleted file mode 100644
index a483ba1..0000000
--- a/src/main/java/com/n1netails/n1netails/slack/model/blocks/FallbackBlock.java
+++ /dev/null
@@ -1,20 +0,0 @@
-package com.n1netails.n1netails.slack.model.blocks;
-
-import com.n1netails.n1netails.slack.model.SlackBlock;
-import com.slack.api.model.block.LayoutBlock;
-import com.slack.api.model.block.composition.PlainTextObject;
-
-public class FallbackBlock implements SlackBlock {
-
-    private final String text;
-
-    public FallbackBlock(String text) {
-        this.text = text;
-    }
-    @Override
-    public LayoutBlock toLayoutBlock() {
-        return com.slack.api.model.block.SectionBlock.builder()
-                .text(new PlainTextObject(text, false))
-                .build();
-    }
-}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java
similarity index 84%
rename from src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java
rename to src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java
index 18e9f5b..9678da3 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/GifBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java
@@ -1,7 +1,7 @@
-package com.n1netails.n1netails.slack.validation.impl;
+package com.n1netails.n1netails.slack.validation.impl.block;
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.blocks.GifBlock;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
 public class GifBlockValidator implements SlackValidator<GifBlock> {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java
similarity index 84%
rename from src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java
rename to src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java
index 2dacdd3..e67ba0c 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/ImageBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java
@@ -1,7 +1,7 @@
-package com.n1netails.n1netails.slack.validation.impl;
+package com.n1netails.n1netails.slack.validation.impl.block;
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.blocks.ImageBlock;
+import com.n1netails.n1netails.slack.model.block.ImageBlock;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
 public class ImageBlockValidator implements SlackValidator<ImageBlock> {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java
similarity index 79%
rename from src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
rename to src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java
index 3161b5d..1ffb414 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/TextBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java
@@ -1,7 +1,7 @@
-package com.n1netails.n1netails.slack.validation.impl;
+package com.n1netails.n1netails.slack.validation.impl.block;
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.blocks.TextBlock;
+import com.n1netails.n1netails.slack.model.block.TextBlock;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
 public class TextBlockValidator implements SlackValidator<TextBlock> {

From 57407ce374ef46a58a3e9fc42e541af06e9c02f3 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 12:37:03 +0100
Subject: [PATCH 25/37] Expose static factory method in ActionsBlock + builder
 option

---
 .../slack/model/block/ActionsBlock.java       | 25 +++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
index d6778eb..da9989b 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
@@ -13,8 +13,12 @@ public class ActionsBlock implements SlackBlock {
 
     private final List<SlackElement> elements;
 
-    public ActionsBlock(List<SlackElement> elements) {
-        this.elements = elements;
+    private ActionsBlock(List<SlackElement> elements) {
+        this.elements = List.copyOf(elements);
+    }
+
+    public static ActionsBlock of(List<SlackElement> elements) {
+        return new ActionsBlock(elements);
     }
 
     @Override
@@ -27,4 +31,21 @@ public LayoutBlock toLayoutBlock() {
                 )
                 .build();
     }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+        private final List<SlackElement> elements = new ArrayList<>();
+
+        public Builder addElement(SlackElement element) {
+            elements.add(element);
+            return this;
+        }
+
+        public ActionsBlock build() {
+            return new ActionsBlock(elements);
+        }
+    }
 }

From e0edfc83386e8b2d3139eda2fcb46c40a211e7d0 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 12:39:35 +0100
Subject: [PATCH 26/37] Expose static factory method in the blocks

---
 .../com/n1netails/n1netails/slack/model/block/GifBlock.java | 6 +++++-
 .../n1netails/n1netails/slack/model/block/ImageBlock.java   | 6 +++++-
 .../n1netails/n1netails/slack/model/block/TextBlock.java    | 6 +++++-
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
index 5b49647..d1b41e5 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
@@ -9,11 +9,15 @@ public class GifBlock implements SlackBlock {
     private final String gifUrl;
     private final String altText;
 
-    public GifBlock(String gifUrl, String altText) {
+    private GifBlock(String gifUrl, String altText) {
         this.gifUrl = gifUrl;
         this.altText = altText;
     }
 
+    public static GifBlock of(String gifUrl, String altText) {
+        return new GifBlock(gifUrl, altText);
+    }
+
 
     @Override
     public LayoutBlock toLayoutBlock() {
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
index 29fb499..669825e 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
@@ -10,11 +10,15 @@ public class ImageBlock implements SlackBlock {
     private final String imageUrl;
     private final String altText;
 
-    public ImageBlock(String imageUrl, String altText) {
+    private ImageBlock(String imageUrl, String altText) {
         this.imageUrl = imageUrl;
         this.altText = altText;
     }
 
+    public ImageBlock of(String imageUrl, String altText) {
+        return new ImageBlock(imageUrl, altText);
+    }
+
 
     @Override
     public LayoutBlock toLayoutBlock() {
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
index ab4b743..e907dc9 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
@@ -9,10 +9,14 @@
 public class TextBlock implements SlackBlock {
     private final String text;
 
-    public TextBlock(String text) {
+    private TextBlock(String text) {
         this.text = text;
     }
 
+    public TextBlock of(String text) {
+        return new TextBlock(text);
+    }
+
     @Override
     public LayoutBlock toLayoutBlock() {
         return com.slack.api.model.block.SectionBlock.builder()

From e1d52cb0132f42803ffc0f371b2a853dab305ffd Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 13:23:00 +0100
Subject: [PATCH 27/37] Button class rename + builder/static factory

---
 .../slack/model/actions_element/Button.java   | 32 ---------
 .../model/actions_element/ButtonElement.java  | 66 +++++++++++++++++++
 .../impl/element/ButtonElementValidator.java  |  6 +-
 3 files changed, 69 insertions(+), 35 deletions(-)
 delete mode 100644 src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java
deleted file mode 100644
index 92fedf1..0000000
--- a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/Button.java
+++ /dev/null
@@ -1,32 +0,0 @@
-package com.n1netails.n1netails.slack.model.actions_element;
-
-import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.SlackElement;
-import com.slack.api.model.block.composition.PlainTextObject;
-import com.slack.api.model.block.element.BlockElement;
-import com.slack.api.model.block.element.ButtonElement;
-import lombok.Getter;
-
-@Getter
-public class Button implements SlackElement {
-    private final String text;
-    private final String actionId;
-    private final String url;
-
-    public Button(String text, String actionId, String url) {
-        this.text = text;
-        this.actionId = actionId;
-        this.url = url;
-    }
-
-    @Override
-    public BlockElement toBlockElement() {
-        return com.slack.api.model.block.element.ButtonElement.builder()
-                .text(com.slack.api.model.block.composition.PlainTextObject.builder()
-                        .text(text)
-                        .build())
-                .actionId(actionId)
-                .url(url)
-                .build();
-    }
-}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
new file mode 100644
index 0000000..354aa33
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
@@ -0,0 +1,66 @@
+package com.n1netails.n1netails.slack.model.actions_element;
+
+import com.n1netails.n1netails.slack.model.SlackElement;
+import com.slack.api.model.block.element.BlockElement;
+import lombok.Getter;
+
+@Getter
+public class ButtonElement implements SlackElement {
+    private final String text;
+    private final String actionId;
+    private final String url;
+
+    private ButtonElement(String text, String actionId, String url) {
+        this.text = text;
+        this.actionId = actionId;
+        this.url = url;
+    }
+
+    public static ButtonElement link(String text, String url) {
+        return new ButtonElement(text, null, url);
+    }
+
+    public static ButtonElement action(String text, String actionId) {
+        return new ButtonElement(text, actionId, null);
+    }
+
+    @Override
+    public BlockElement toBlockElement() {
+        return com.slack.api.model.block.element.ButtonElement.builder()
+                .text(com.slack.api.model.block.composition.PlainTextObject.builder()
+                        .text(text)
+                        .build())
+                .actionId(actionId)
+                .url(url)
+                .build();
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+        private String text;
+        private String actionId;
+        private String url;
+
+        public Builder text(String text) {
+            this.text = text;
+            return this;
+        }
+
+        public Builder actionId(String actionId) {
+            this.actionId = actionId;
+            return this;
+        }
+
+        public Builder url(String url) {
+            this.url = url;
+            return this;
+        }
+
+        public ButtonElement build() {
+            return new ButtonElement(text, actionId, url);
+        }
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
index c641d5e..de80f8d 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
@@ -1,12 +1,12 @@
 package com.n1netails.n1netails.slack.validation.impl.element;
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.actions_element.Button;
+import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
-public class ButtonElementValidator implements SlackValidator<Button> {
+public class ButtonElementValidator implements SlackValidator<ButtonElement> {
     @Override
-    public void validate(Button target) throws SlackValidationException {
+    public void validate(ButtonElement target) throws SlackValidationException {
         if (target.getText() == null || target.getText().isBlank()) {
             throw new SlackValidationException("Button text is required");
         }

From 7236cefa39f06547efb60569dee996a6a2e8891a Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 13:42:36 +0100
Subject: [PATCH 28/37] internal validation on Elements is on

---
 .../n1netails/slack/validation/BasicSlackValidators.java       | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index b01d5da..badf71d 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.validation;
 
+import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.n1netails.n1netails.slack.model.block.ActionsBlock;
 import com.n1netails.n1netails.slack.model.block.GifBlock;
 import com.n1netails.n1netails.slack.model.block.ImageBlock;
@@ -8,6 +9,7 @@
 import com.n1netails.n1netails.slack.validation.impl.block.GifBlockValidator;
 import com.n1netails.n1netails.slack.validation.impl.block.ImageBlockValidator;
 import com.n1netails.n1netails.slack.validation.impl.block.TextBlockValidator;
+import com.n1netails.n1netails.slack.validation.impl.element.ButtonElementValidator;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -25,6 +27,7 @@ private void init() {
         validators.put(GifBlock.class, new GifBlockValidator());
         validators.put(TextBlock.class, new TextBlockValidator());
         validators.put(ActionsBlock.class, new ActionsBlockValidator(this));
+        validators.put(ButtonElement.class, new ButtonElementValidator());
     }
 
     public <T> void validate(T target) {

From 428fef15e9af08157c7ca7e97f155ebc9c7a4ac3 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 13:46:20 +0100
Subject: [PATCH 29/37] builder option for other blocks

---
 .../n1netails/slack/model/block/GifBlock.java | 20 +++++++++++++++++++
 .../slack/model/block/ImageBlock.java         | 20 +++++++++++++++++++
 .../slack/model/block/TextBlock.java          | 15 ++++++++++++++
 3 files changed, 55 insertions(+)

diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
index d1b41e5..3342ca2 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.model.block;
 
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
@@ -28,4 +29,23 @@ public LayoutBlock toLayoutBlock() {
                         .build()
                 ;
     }
+
+    public static class Builder {
+        private String gifUrl;
+        private String altText;
+
+        public Builder gifUrl(String gifUrl) {
+            this.gifUrl = gifUrl;
+            return this;
+        }
+
+        public Builder altText(String altText) {
+            this.altText = altText;
+            return this;
+        }
+
+        public GifBlock build() {
+            return new GifBlock(gifUrl, altText);
+        }
+    }
 }
\ No newline at end of file
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
index 669825e..66e227e 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.model.block;
 
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
@@ -29,4 +30,23 @@ public LayoutBlock toLayoutBlock() {
                         .build()
                 ;
     }
+
+    public static class Builder {
+        private String imageUrl;
+        private String altText;
+
+        public Builder imageUrl(String imageUrl) {
+            this.imageUrl = imageUrl;
+            return this;
+        }
+
+        public Builder altText(String altText) {
+            this.altText = altText;
+            return this;
+        }
+
+        public ImageBlock build() {
+            return new ImageBlock(imageUrl, altText);
+        }
+    }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
index e907dc9..19cf327 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.model.block;
 
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.slack.api.model.block.LayoutBlock;
 import com.slack.api.model.block.composition.PlainTextObject;
@@ -23,4 +24,18 @@ public LayoutBlock toLayoutBlock() {
                 .text(new PlainTextObject(text, false))
                 .build();
     }
+
+    public static class Builder {
+        private String text;
+
+        public Builder text(String text) {
+            this.text = text;
+            return this;
+        }
+
+        public TextBlock build() {
+            return new TextBlock(text);
+        }
+    }
+
 }

From 06a613de4707a7f1c05aca322aca1f8c2bc5825a Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 20:38:09 +0100
Subject: [PATCH 30/37] separate block validation and block building

---
 .../n1netails/slack/api/BotService.java       | 37 ++++++-----
 .../slack/api/builder/SlackBlockBuilder.java  | 26 ++++++++
 .../slack/exception/SlackErrorMapper.java     | 29 +++++----
 .../n1netails/slack/model/SlackBlock.java     |  2 +-
 .../n1netails/slack/model/SlackElement.java   |  2 +-
 .../n1netails/slack/model/SlackNode.java      |  7 +++
 .../model/actions_element/ButtonElement.java  |  8 +++
 .../slack/model/block/ActionsBlock.java       |  6 ++
 .../n1netails/slack/model/block/GifBlock.java |  8 +++
 .../slack/model/block/ImageBlock.java         |  8 +++
 .../slack/model/block/TextBlock.java          |  8 +++
 .../slack/processing/SlackBlockProcessor.java | 63 -------------------
 .../validation/BasicSlackValidators.java      |  2 +-
 .../slack/validation/SlackBlockValidator.java | 54 ++++++++++++++++
 .../impl/block/ActionsBlockValidator.java     | 10 ---
 15 files changed, 164 insertions(+), 106 deletions(-)
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java
 delete mode 100644 src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java
 create mode 100644 src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 00616ad..11c9722 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -1,11 +1,12 @@
 package com.n1netails.n1netails.slack.api;
 
+import com.n1netails.n1netails.slack.api.builder.SlackBlockBuilder;
 import com.n1netails.n1netails.slack.exception.SlackErrorMapper;
 import com.n1netails.n1netails.slack.exception.SlackClientException;
 import com.n1netails.n1netails.slack.exception.SlackTransportException;
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.processing.SlackBlockProcessor;
+import com.n1netails.n1netails.slack.validation.SlackBlockValidator;
 import com.slack.api.Slack;
 import com.slack.api.methods.MethodsClient;
 import com.slack.api.methods.SlackApiException;
@@ -23,7 +24,8 @@
  */
 class BotService {
     private final MethodsClient methods;
-    private final SlackBlockProcessor blockProcessor;
+    private final SlackBlockValidator blockValidator;
+    private final SlackBlockBuilder blockBuilder;
 
     /**
      * Bot Service Constructor
@@ -32,14 +34,26 @@ class BotService {
      */
     public BotService(String token) {
         this.methods = Slack.getInstance().methods(token);
-        this.blockProcessor = new SlackBlockProcessor();
+        this.blockValidator = new SlackBlockValidator();
+        this.blockBuilder = new SlackBlockBuilder();
 
     }
 
     public void send(SlackMessage slackMessage) throws SlackClientException {
         validateBasic(slackMessage);
+
+        blockValidator.validateMessageBlocks(slackMessage);
+
         try {
-            ChatPostMessageRequest request = buildRequest(slackMessage);
+            List<LayoutBlock> blocks = blockBuilder.build(slackMessage);
+
+            ChatPostMessageRequest request =
+                    ChatPostMessageRequest.builder()
+                            .channel(slackMessage.getChannel())
+                            .text(slackMessage.getText())
+                            .blocks(blocks)
+                            .build();
+
             ChatPostMessageResponse response = methods.chatPostMessage(request);
             if (!response.isOk()) {
                 throw SlackErrorMapper.map(response);
@@ -64,19 +78,4 @@ private void validateBasic(SlackMessage message) throws SlackValidationException
             throw new SlackValidationException("Message must contain text or blocks");
         }
     }
-
-
-    private ChatPostMessageRequest buildRequest(SlackMessage slackMessage) {
-        ChatPostMessageRequest.ChatPostMessageRequestBuilder requestBuilder =
-                ChatPostMessageRequest.builder()
-                        .channel(slackMessage.getChannel())
-                        .text(slackMessage.getText());
-
-        List<LayoutBlock> blocks = blockProcessor.process(slackMessage);
-        if ((blocks != null && !blocks.isEmpty()))
-            requestBuilder.blocks(blocks);
-        return requestBuilder.build();
-    }
-
-
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java b/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
new file mode 100644
index 0000000..b049b90
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
@@ -0,0 +1,26 @@
+package com.n1netails.n1netails.slack.api.builder;
+
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackMessage;
+import com.slack.api.model.block.LayoutBlock;
+
+import java.util.List;
+
+public class SlackBlockBuilder {
+
+    public List<LayoutBlock> build(SlackMessage message) {
+
+        if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
+            return message.getRawBlocks();
+        }
+
+        if (message.getBlocks() == null || message.getBlocks().isEmpty()) {
+            return null;
+        }
+
+        return message.getBlocks()
+                .stream()
+                .map(SlackBlock::toLayoutBlock)
+                .toList();
+    }
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
index 52f1de5..62aa629 100644
--- a/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
@@ -41,25 +41,32 @@ private static String format(String rawError) {
             return message;
 
         } catch (Exception e) {
-            return rawError; // fallback
+            return rawError;
         }
     }
 
     private static String mapPointer(String pointer, String message) {
         String[] parts = pointer.split("/");
 
-        if (parts.length >= 4 && "blocks".equals(parts[1])) {
-            int index = Integer.parseInt(parts[2]);
-            String field = parts[3];
+        StringBuilder path = new StringBuilder();
 
-            return String.format(
-                    "Block[%d].%s: %s",
-                    index,
-                    field,
-                    message
-            );
+        for (int i = 1; i < parts.length; i++) {
+            String part = parts[i];
+
+            if (isNumeric(part)) {
+                path.append("[").append(part).append("]");
+            } else {
+                if (!path.isEmpty()) {
+                    path.append(".");
+                }
+                path.append(part);
+            }
         }
 
-        return pointer + ": " + message;
+        return path + ": " + message;
+    }
+
+    private static boolean isNumeric(String str) {
+        return str.chars().allMatch(Character::isDigit);
     }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
index ced5e45..cad9a33 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
@@ -4,6 +4,6 @@
 
 import java.util.List;
 
-public interface SlackBlock {
+public interface SlackBlock extends SlackNode {
     LayoutBlock toLayoutBlock();
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
index 1044e6c..919ef41 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
@@ -2,6 +2,6 @@
 
 import com.slack.api.model.block.element.BlockElement;
 
-public interface SlackElement {
+public interface SlackElement extends SlackNode {
     BlockElement toBlockElement();
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java
new file mode 100644
index 0000000..0752ac0
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java
@@ -0,0 +1,7 @@
+package com.n1netails.n1netails.slack.model;
+
+import java.util.List;
+
+public interface SlackNode {
+    List<SlackNode> getChildren();
+}
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
index 354aa33..0d8e56c 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
@@ -1,9 +1,12 @@
 package com.n1netails.n1netails.slack.model.actions_element;
 
 import com.n1netails.n1netails.slack.model.SlackElement;
+import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.element.BlockElement;
 import lombok.Getter;
 
+import java.util.List;
+
 @Getter
 public class ButtonElement implements SlackElement {
     private final String text;
@@ -39,6 +42,11 @@ public static Builder builder() {
         return new Builder();
     }
 
+    @Override
+    public List<SlackNode> getChildren() {
+        return List.of();
+    }
+
     public static class Builder {
         private String text;
         private String actionId;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
index da9989b..a97a551 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
@@ -2,6 +2,7 @@
 
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackElement;
+import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
 
@@ -36,6 +37,11 @@ public static Builder builder() {
         return new Builder();
     }
 
+    @Override
+    public List<SlackNode> getChildren() {
+        return List.copyOf(elements);
+    }
+
     public static class Builder {
         private final List<SlackElement> elements = new ArrayList<>();
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
index 3342ca2..ab57d0a 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
@@ -2,9 +2,12 @@
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
 
+import java.util.List;
+
 @Getter
 public class GifBlock implements SlackBlock {
     private final String gifUrl;
@@ -30,6 +33,11 @@ public LayoutBlock toLayoutBlock() {
                 ;
     }
 
+    @Override
+    public List<SlackNode> getChildren() {
+        return List.of();
+    }
+
     public static class Builder {
         private String gifUrl;
         private String altText;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
index 66e227e..67d4719 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
@@ -2,9 +2,12 @@
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
 
+import java.util.List;
+
 
 @Getter
 public class ImageBlock implements SlackBlock {
@@ -31,6 +34,11 @@ public LayoutBlock toLayoutBlock() {
                 ;
     }
 
+    @Override
+    public List<SlackNode> getChildren() {
+        return List.of();
+    }
+
     public static class Builder {
         private String imageUrl;
         private String altText;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
index 19cf327..5af9784 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
@@ -2,10 +2,13 @@
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.LayoutBlock;
 import com.slack.api.model.block.composition.PlainTextObject;
 import lombok.Getter;
 
+import java.util.List;
+
 @Getter
 public class TextBlock implements SlackBlock {
     private final String text;
@@ -25,6 +28,11 @@ public LayoutBlock toLayoutBlock() {
                 .build();
     }
 
+    @Override
+    public List<SlackNode> getChildren() {
+        return List.of();
+    }
+
     public static class Builder {
         private String text;
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java b/src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java
deleted file mode 100644
index 723f511..0000000
--- a/src/main/java/com/n1netails/n1netails/slack/processing/SlackBlockProcessor.java
+++ /dev/null
@@ -1,63 +0,0 @@
-package com.n1netails.n1netails.slack.processing;
-
-import com.n1netails.n1netails.slack.exception.SlackValidationException;
-import com.n1netails.n1netails.slack.model.SlackBlock;
-import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.validation.BasicSlackValidators;
-import com.slack.api.model.block.LayoutBlock;
-
-import java.util.ArrayList;
-import java.util.List;
-
-public class SlackBlockProcessor {
-
-    private final BasicSlackValidators basicSlackValidators;
-
-    public SlackBlockProcessor() {
-        this.basicSlackValidators = new BasicSlackValidators();
-    }
-
-    public List<LayoutBlock> process(SlackMessage message) {
-        if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
-            return message.getRawBlocks();
-        }
-
-        if (message.getBlocks() == null || message.getBlocks().isEmpty()) {
-            return null;
-        }
-
-        List<LayoutBlock> result = new ArrayList<>();
-        List<String> errors = new ArrayList<>();
-
-        int index = 0;
-
-        for (SlackBlock block : message.getBlocks()) {
-            try {
-                basicSlackValidators.validate(block);
-                result.add(block.toLayoutBlock());
-            } catch (SlackValidationException e) {
-                errors.add(formatError(index, block, e));
-            }
-            index++;
-        }
-
-        if (!errors.isEmpty()) {
-            throw new SlackValidationException(buildErrorMessage(errors));
-        }
-
-        return result;
-    }
-
-    private String formatError(int index, SlackBlock block, Exception e) {
-        return String.format(
-                "Block[%d] (%s): %s",
-                index,
-                block.getClass().getSimpleName(),
-                e.getMessage()
-        );
-    }
-
-    private String buildErrorMessage(List<String> errors) {
-        return "Slack message validation failed:\n - " + String.join("\n - ", errors);
-    }
-}
\ No newline at end of file
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index badf71d..612fa3a 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -26,7 +26,7 @@ private void init() {
         validators.put(ImageBlock.class, new ImageBlockValidator());
         validators.put(GifBlock.class, new GifBlockValidator());
         validators.put(TextBlock.class, new TextBlockValidator());
-        validators.put(ActionsBlock.class, new ActionsBlockValidator(this));
+        validators.put(ActionsBlock.class, new ActionsBlockValidator());
         validators.put(ButtonElement.class, new ButtonElementValidator());
     }
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
new file mode 100644
index 0000000..bf33d41
--- /dev/null
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
@@ -0,0 +1,54 @@
+package com.n1netails.n1netails.slack.validation;
+
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.SlackBlock;
+import com.n1netails.n1netails.slack.model.SlackMessage;
+import com.n1netails.n1netails.slack.model.SlackNode;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class SlackBlockValidator {
+
+    private final BasicSlackValidators basicSlackValidators;
+
+    public SlackBlockValidator() {
+        this.basicSlackValidators = new BasicSlackValidators();
+    }
+
+    public void validateMessageBlocks(SlackMessage message) {
+        if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
+            return;
+        }
+
+        if (message.getBlocks() == null || message.getBlocks().isEmpty()) {
+            return;
+        }
+
+        List<String> errors = new ArrayList<>();
+
+        for (int i = 0; i < message.getBlocks().size(); i++) {
+            SlackBlock block = message.getBlocks().get(i);
+            validateNode(block, "Block[" + i + "]", errors);
+        }
+
+        if (!errors.isEmpty()) {
+            throw new SlackValidationException(
+                    "Slack message validation failed:\n - " + String.join("\n - ", errors)
+            );
+        }
+    }
+
+    private void validateNode(SlackNode node, String path, List<String> errors) {
+        try {
+            basicSlackValidators.validate(node);
+        } catch (SlackValidationException e) {
+            errors.add(path + " (" + node.getClass().getSimpleName() + "): " + e.getMessage());
+        }
+
+        List<SlackNode> children = node.getChildren();
+        for (int i = 0; i < children.size(); i++) {
+            validateNode(children.get(i), path + ".elements[" + i + "]", errors);
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
index ed5a8d6..c7bf0bf 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
@@ -7,21 +7,11 @@
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
 public class ActionsBlockValidator implements SlackValidator<ActionsBlock> {
-    private final BasicSlackValidators validators;
-
-    public ActionsBlockValidator(BasicSlackValidators validators) {
-        this.validators = validators;
-    }
-
     @Override
     public void validate(ActionsBlock target) throws SlackValidationException {
         if (target.getElements() == null || target.getElements().isEmpty()) {
             throw new SlackValidationException("ActionsBlock must contain at least one element");
         }
 
-
-        for (SlackElement element : target.getElements()) {
-            validators.validate(element);
-        }
     }
 }

From e54adfcbdc939b974c56bb4eccc5e8a243bb9051 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 21:07:33 +0100
Subject: [PATCH 31/37] a bit of encapsulation

---
 .../com/n1netails/n1netails/slack/api/BotService.java     | 2 +-
 .../slack/exception/SlackApiExceptionWrapper.java         | 8 --------
 .../n1netails/slack/validation/BasicSlackValidators.java  | 2 +-
 .../validation/impl/element/ButtonElementValidator.java   | 1 -
 4 files changed, 2 insertions(+), 11 deletions(-)
 delete mode 100644 src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 11c9722..33fccbe 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -22,7 +22,7 @@
  *
  * @author shahid foy
  */
-class BotService {
+final class BotService {
     private final MethodsClient methods;
     private final SlackBlockValidator blockValidator;
     private final SlackBlockBuilder blockBuilder;
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
deleted file mode 100644
index 84dffdc..0000000
--- a/src/main/java/com/n1netails/n1netails/slack/exception/SlackApiExceptionWrapper.java
+++ /dev/null
@@ -1,8 +0,0 @@
-package com.n1netails.n1netails.slack.exception;
-
-public class SlackApiExceptionWrapper extends SlackClientException {
-    public SlackApiExceptionWrapper(String slackError) {
-        super("Slack API error: " + slackError);
-
-    }
-}
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index 612fa3a..ce84f1b 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -18,7 +18,7 @@ public class BasicSlackValidators {
     private final Map<Class<?>, SlackValidator<?>> validators = new HashMap<>();
 
 
-    public BasicSlackValidators() {
+    BasicSlackValidators() {
         init();
     }
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
index de80f8d..67ea6ef 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
@@ -16,6 +16,5 @@ public void validate(ButtonElement target) throws SlackValidationException {
                     "Button must have either actionId or url"
             );
         }
-
     }
 }

From 58baa103584e8e3a2f666b1b0745019a34f1a1c6 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 22:02:07 +0100
Subject: [PATCH 32/37] javadocs

---
 .../n1netails/slack/api/BotService.java       | 51 +++++++++++--
 .../n1netails/slack/api/SlackClient.java      | 48 +++++++++++--
 .../n1netails/slack/api/SlackClientImpl.java  | 30 +++++---
 .../slack/api/builder/SlackBlockBuilder.java  | 29 ++++++++
 .../slack/exception/SlackErrorMapper.java     | 47 ++++++++++++
 .../n1netails/slack/model/SlackBlock.java     | 28 ++++++++
 .../n1netails/slack/model/SlackElement.java   | 25 +++++++
 .../n1netails/slack/model/SlackMessage.java   | 71 ++++++++++++++++++-
 .../n1netails/slack/model/SlackNode.java      | 31 ++++++++
 .../model/actions_element/ButtonElement.java  | 18 +++++
 .../slack/model/block/ActionsBlock.java       | 22 ++++++
 .../n1netails/slack/model/block/GifBlock.java | 24 +++++++
 .../slack/model/block/ImageBlock.java         | 24 ++++++-
 .../slack/model/block/TextBlock.java          | 20 ++++++
 .../validation/BasicSlackValidators.java      | 30 ++++++++
 .../slack/validation/SlackBlockValidator.java | 46 ++++++++++++
 .../slack/validation/SlackValidator.java      | 21 ++++++
 .../impl/block/ActionsBlockValidator.java     | 18 +++++
 .../impl/block/GifBlockValidator.java         | 16 +++++
 .../impl/block/ImageBlockValidator.java       | 16 +++++
 .../impl/block/TextBlockValidator.java        | 17 +++++
 .../impl/element/ButtonElementValidator.java  | 23 ++++++
 22 files changed, 634 insertions(+), 21 deletions(-)

diff --git a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
index 33fccbe..4948c7b 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/BotService.java
@@ -18,19 +18,39 @@
 import java.util.List;
 
 /**
- * Slack Bot Service
+ * Service responsible for sending messages to Slack via the Slack SDK.
+ * <p>
+ * Encapsulates the Slack {@link MethodsClient}, performs message validation,
+ * and builds message blocks using {@link SlackBlockBuilder}.
+ * Handles transport and validation exceptions internally.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * BotService botService = new BotService("xoxb-your-token");
+ * SlackMessage message = new SlackMessage("general", "Hello, Slack!");
+ * botService.send(message);
+ * }</pre>
  *
- * @author shahid foy
+ * <p>All messages are validated before sending. Text or blocks must be present
+ * in the {@link SlackMessage}, otherwise a {@link SlackValidationException} is thrown.</p>
+ *
+ * <p>Exceptions thrown:</p>
+ * <ul>
+ *     <li>{@link SlackTransportException} – for network/SDK errors</li>
+ * </ul>
+ *
+ * @author Shahid Foy and Artur Slimak
  */
-final class BotService {
+final public class BotService {
     private final MethodsClient methods;
     private final SlackBlockValidator blockValidator;
     private final SlackBlockBuilder blockBuilder;
 
     /**
-     * Bot Service Constructor
+     * Constructs a new {@link BotService} with the given Slack bot token.
      *
-     * @param token slack bot token
+     * @param token Slack bot token for authentication; must not be null or blank
      */
     public BotService(String token) {
         this.methods = Slack.getInstance().methods(token);
@@ -39,6 +59,17 @@ public BotService(String token) {
 
     }
 
+
+    /**
+     * Sends a {@link SlackMessage} to Slack.
+     * <p>
+     * The message is validated for basic requirements (text or blocks present),
+     * and all blocks are validated via {@link SlackBlockValidator}.
+     * </p>
+     *
+     * @param slackMessage the message to send; must not be null
+     * @throws SlackClientException if validation fails or sending fails due to network/Slack API errors
+     */
     public void send(SlackMessage slackMessage) throws SlackClientException {
         validateBasic(slackMessage);
 
@@ -65,7 +96,15 @@ public void send(SlackMessage slackMessage) throws SlackClientException {
         }
     }
 
-
+    /**
+     * Performs basic validation on a {@link SlackMessage}.
+     * <p>
+     * Ensures that the message is not null and contains either text, blocks, or raw blocks.
+     * </p>
+     *
+     * @param message the Slack message to validate
+     * @throws SlackValidationException if the message is null or contains no text/blocks
+     */
     private void validateBasic(SlackMessage message) throws SlackValidationException {
         if (message == null) {
             throw new SlackValidationException("SlackMessage cannot be null");
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
index 4cb0bd9..3c18228 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClient.java
@@ -5,26 +5,66 @@
 import com.n1netails.n1netails.slack.model.SlackMessage;
 
 /**
- * Slick Client
+ * Slack Client interface for sending messages to Slack.
+ * <p>
+ * This is a sealed interface, allowing only {@link SlackClientImpl} to implement it.
+ * Use the {@link #builder()} method to create instances.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * SlackClient client = SlackClient.builder()
+ *                                 .token("xoxb-your-token")
+ *                                 .build();
+ * client.sendMessage(new SlackMessage("Hello, Slack!"));
+ * }</pre>
  *
- * @author shahid foy
+ * <p>All implementations are expected to handle exceptions via {@link SlackClientException}.</p>
+ *
+ * @author Shahid Foy and Artur Slimak
  */
 public sealed interface SlackClient permits SlackClientImpl {
 
     /**
-     * Send slack message
+     * Sends a message to Slack.
      *
-     * @param slackMessage slack message
+     * @param slackMessage the message to send, must not be null
+     * @throws SlackClientException if sending fails (network, authentication, or other Slack API issues)
      */
     void sendMessage(SlackMessage slackMessage) throws SlackClientException;
 
+    /**
+     * Returns a new {@link Builder} for constructing a {@link SlackClient}.
+     *
+     * @return a new builder instance
+     */
     static Builder builder() {
         return new SlackClientImpl.Builder();
     }
 
+    /**
+     * Builder interface for {@link SlackClient}.
+     * <p>
+     * This is a sealed interface, allowing only {@link SlackClientImpl.Builder} to implement it.
+     * Provides a fluent API for setting configuration parameters.
+     * </p>
+     */
     sealed interface Builder permits SlackClientImpl.Builder {
+
+        /**
+         * Sets the Slack authentication token.
+         *
+         * @param token the OAuth token for Slack API access
+         * @return this builder instance
+         */
         Builder token(String token);
 
+        /**
+         * Builds the {@link SlackClient} instance using the provided configuration.
+         *
+         * @return a configured {@link SlackClient}
+         * @throws SlackClientException if required parameters are missing or invalid
+         */
         SlackClient build() throws SlackClientException;
     }
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
index 6b96f3c..fbd4b37 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/SlackClientImpl.java
@@ -4,28 +4,42 @@
 import com.n1netails.n1netails.slack.model.SlackMessage;
 
 /**
- * Slack Client Implementation
+ * Concrete implementation of {@link SlackClient}.
+ * <p>
+ * Uses {@link BotService} internally to send messages to Slack.
+ * Created via {@link SlackClientImpl.Builder}.
+ * </p>
  *
- * @author shahid foy
+ * Example:
+ * <pre>{@code
+ * SlackClient client = SlackClientImpl.builder()
+ *                                     .token("xoxb-your-token")
+ *                                     .build();
+ * client.sendMessage(new SlackMessage("Hello!"));
+ * }</pre>
+ *
+ * @author Artur Slimak
  */
 final class SlackClientImpl implements SlackClient {
 
     private final BotService botService;
 
-    public SlackClientImpl(Builder builder) {
+    private SlackClientImpl(Builder builder) {
         this.botService = new BotService(builder.token);
     }
 
-    /**
-     * Send slack notification
-     *
-     * @param slackMessage slack message
-     */
     @Override
     public void sendMessage(SlackMessage slackMessage) throws SlackClientException {
         botService.send(slackMessage);
     }
 
+    /**
+     * Builder for {@link SlackClientImpl}.
+     * <p>
+     * Implements the {@link SlackClient.Builder} interface.
+     * Used to configure and construct an instance of {@link SlackClientImpl}.
+     * </p>
+     */
     public static final class Builder implements SlackClient.Builder {
         private String token;
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java b/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
index b049b90..6308bc3 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
@@ -6,8 +6,37 @@
 
 import java.util.List;
 
+/**
+ * Builder class responsible for converting a {@link SlackMessage} into a list of Slack {@link LayoutBlock}s.
+ * <p>
+ * The builder first checks if the message contains raw {@link LayoutBlock}s. If so, it returns them directly.
+ * Otherwise, it converts the high-level {@link SlackBlock} objects into {@link LayoutBlock}s using their {@code toLayoutBlock()} method.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * SlackMessage message = new SlackMessage("general", "Hello!");
+ * List<LayoutBlock> blocks = new SlackBlockBuilder().build(message);
+ * }</pre>
+ *
+ * @author Artur Slimak
+ */
 public class SlackBlockBuilder {
 
+    /**
+     * Builds a list of {@link LayoutBlock}s from a {@link SlackMessage}.
+     * <p>
+     * Priority order:
+     * <ol>
+     *     <li>If {@code rawBlocks} are present in the message, return them as-is.</li>
+     *     <li>If {@code blocks} are present, convert each {@link SlackBlock} to {@link LayoutBlock}.</li>
+     *     <li>If neither is present, returns {@code null}.</li>
+     * </ol>
+     * </p>
+     *
+     * @param message the Slack message to convert; must not be null
+     * @return list of {@link LayoutBlock}s or {@code null} if none are available
+     */
     public List<LayoutBlock> build(SlackMessage message) {
 
         if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
diff --git a/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java b/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
index 62aa629..48170d4 100644
--- a/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
+++ b/src/main/java/com/n1netails/n1netails/slack/exception/SlackErrorMapper.java
@@ -5,8 +5,34 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Utility class for mapping Slack API {@link ChatPostMessageResponse} errors
+ * into human-readable {@link SlackValidationException} messages.
+ * <p>
+ * This class parses raw Slack API error messages, including JSON pointers,
+ * and formats them for easier debugging and display in your application.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ChatPostMessageResponse response = methodsClient.chatPostMessage(request);
+ * if (!response.isOk()) {
+ *     throw SlackErrorMapper.map(response);
+ * }
+ * }</pre>
+ *
+ * <p>Implements static, stateless methods and is thread-safe.</p>
+ *
+ * @author Artur Slimak
+ */
 public class SlackErrorMapper {
 
+    /**
+     * Maps a {@link ChatPostMessageResponse} from the Slack API into a {@link SlackValidationException}.
+     *
+     * @param response the Slack API response
+     * @return a {@link SlackValidationException} containing formatted error messages
+     */
     public static SlackValidationException map(ChatPostMessageResponse response) {
         if (response.getErrors() == null || response.getErrors().isEmpty()) {
             return new SlackValidationException(response.getError());
@@ -23,6 +49,12 @@ public static SlackValidationException map(ChatPostMessageResponse response) {
         );
     }
 
+    /**
+     * Formats a raw Slack API error message, including parsing JSON pointers if present.
+     *
+     * @param rawError the raw error string from Slack API
+     * @return a human-readable formatted error message
+     */
     private static String format(String rawError) {
         try {
             String message = rawError;
@@ -45,6 +77,14 @@ private static String format(String rawError) {
         }
     }
 
+
+    /**
+     * Maps a JSON pointer from Slack API errors into a readable path format.
+     *
+     * @param pointer the JSON pointer string (e.g., "/blocks/0/elements/1")
+     * @param message the original error message
+     * @return a human-readable error with the pointer path
+     */
     private static String mapPointer(String pointer, String message) {
         String[] parts = pointer.split("/");
 
@@ -66,6 +106,13 @@ private static String mapPointer(String pointer, String message) {
         return path + ": " + message;
     }
 
+
+    /**
+     * Checks if a string is numeric.
+     *
+     * @param str the string to check
+     * @return {@code true} if the string consists only of digits, {@code false} otherwise
+     */
     private static boolean isNumeric(String str) {
         return str.chars().allMatch(Character::isDigit);
     }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
index cad9a33..80217e4 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackBlock.java
@@ -1,9 +1,37 @@
 package com.n1netails.n1netails.slack.model;
 
+import com.n1netails.n1netails.slack.model.block.ActionsBlock;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
+import com.n1netails.n1netails.slack.model.block.ImageBlock;
+import com.n1netails.n1netails.slack.model.block.TextBlock;
 import com.slack.api.model.block.LayoutBlock;
 
 import java.util.List;
 
+/**
+ * Represents a Slack block element that can be converted into a Slack API {@link LayoutBlock}.
+ * <p>
+ * All concrete Slack blocks (e.g., {@link TextBlock}, {@link ImageBlock}, {@link GifBlock}, {@link ActionsBlock})
+ * should implement this interface.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * SlackBlock block = TextBlock.of("Hello Slack!");
+ * LayoutBlock layoutBlock = block.toLayoutBlock();
+ * }</pre>
+ *
+ * <p>Extends {@link SlackNode}, allowing blocks to participate in SlackNode hierarchies for compositional validation.</p>
+ *
+ * <p>Implementations should be immutable wherever possible.</p>
+ *
+ * @author Artur Slimak
+ */
 public interface SlackBlock extends SlackNode {
+    /**
+     * Converts this Slack block into a Slack API {@link LayoutBlock}.
+     *
+     * @return the Slack API representation of this block
+     */
     LayoutBlock toLayoutBlock();
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
index 919ef41..636c36c 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackElement.java
@@ -1,7 +1,32 @@
 package com.n1netails.n1netails.slack.model;
 
+import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.slack.api.model.block.element.BlockElement;
 
+/**
+ * Represents a Slack interactive element that can be converted into a Slack API {@link BlockElement}.
+ * <p>
+ * Examples of Slack elements include buttons, select menus, and other interactive UI components.
+ * All concrete elements (e.g., {@link ButtonElement}) should implement this interface.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * SlackElement button = ButtonElement.link("Open URL", "https://example.com");
+ * BlockElement blockElement = button.toBlockElement();
+ * }</pre>
+ *
+ * <p>Extends {@link SlackNode}, allowing elements to participate in SlackNode hierarchies for compositional validation.</p>
+ *
+ * <p>Implementations should be immutable wherever possible.</p>
+ *
+ * @author Artur Slimak
+ */
 public interface SlackElement extends SlackNode {
+    /**
+     * Converts this Slack element into a Slack API {@link BlockElement}.
+     *
+     * @return the Slack API representation of this element
+     */
     BlockElement toBlockElement();
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
index 825e81c..c751556 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackMessage.java
@@ -8,9 +8,26 @@
 import java.util.List;
 
 /**
- * Slack Message
+ * Represents a Slack message that can be sent to a channel.
+ * <p>
+ * A Slack message can contain plain text, structured {@link SlackBlock}s, or raw Slack API blocks
+ * (<a href="https://docs.slack.dev/block-kit">Block Kit Documentation</a>).
+ * Messages are immutable once built and should be constructed via the {@link Builder}.
+ * </p>
  *
- * @author shahid foy
+ * Example usage:
+ * <pre>{@code
+ * SlackMessage message = SlackMessage.builder()
+ *     .channel("general")
+ *     .text("Hello, Slack!")
+ *     .build();
+ * }</pre>
+ *
+ * <p>Cannot mix {@link SlackBlock} and raw Block Kit blocks in the same message.</p>
+ *
+ * <p>All instances are immutable and thread-safe after creation.</p>
+ *
+ * @author Shahid Foy and Artur Slimak
  */
 @Getter
 public class SlackMessage {
@@ -28,26 +45,63 @@ private SlackMessage(Builder builder) {
     }
 
 
+    /**
+     * Returns a new {@link Builder} for constructing a {@link SlackMessage}.
+     *
+     * @return a new builder instance
+     */
     public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Builder class for creating {@link SlackMessage} instances.
+     * <p>
+     * Allows setting the target channel, text, and adding blocks (either {@link SlackBlock} or raw {@link LayoutBlock}).
+     * Enforces validation rules to prevent invalid combinations.
+     * </p>
+     */
     public static class Builder {
         private String channel;
         private String text;
         private final List<SlackBlock> blocks = new ArrayList<>();
         private final List<LayoutBlock> rawBlocks = new ArrayList<>();
 
+        /**
+         * Sets the target Slack channel for this message.
+         *
+         * @param channel the Slack channel name or ID
+         * @return this builder
+         */
         public Builder channel(String channel) {
             this.channel = channel;
             return this;
         }
 
+
+        /**
+         * Sets the plain text content of this Slack message.
+         * <p>
+         * If one or more blocks are present in the message, this text serves as a fallback
+         * for notifications or clients that cannot render blocks.
+         * </p>
+         *
+         * @param text the message text
+         * @return this builder
+         */
         public Builder text(String text) {
             this.text = text;
             return this;
         }
 
+
+        /**
+         * Adds a structured {@link SlackBlock} to this message.
+         *
+         * @param block the Slack block to add
+         * @return this builder
+         * @throws SlackValidationException if rawBlocks are already present
+         */
         public Builder addBlock(SlackBlock block) throws SlackValidationException {
             if (!rawBlocks.isEmpty()) {
                 throw new SlackValidationException(
@@ -58,6 +112,13 @@ public Builder addBlock(SlackBlock block) throws SlackValidationException {
             return this;
         }
 
+        /**
+         * Adds a raw {@link LayoutBlock} to this message.
+         *
+         * @param block the raw Slack API layout block (<a href="https://docs.slack.dev/block-kit">Block Kit Documentation</a>)
+         * @return this builder
+         * @throws SlackValidationException if SlackBlocks are already present
+         */
         public Builder addRawBlock(LayoutBlock block) throws SlackValidationException {
             if (!blocks.isEmpty()) {
                 throw new SlackValidationException(
@@ -68,6 +129,12 @@ public Builder addRawBlock(LayoutBlock block) throws SlackValidationException {
             return this;
         }
 
+        /**
+         * Builds an immutable {@link SlackMessage} instance after performing validation.
+         *
+         * @return a new {@link SlackMessage}
+         * @throws SlackValidationException if channel is missing, content is missing, or block types are mixed
+         */
         public SlackMessage build() throws SlackValidationException {
             if (channel == null || channel.isBlank()) {
                 throw new SlackValidationException("channel is required");
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java b/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java
index 0752ac0..2079948 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/SlackNode.java
@@ -1,7 +1,38 @@
 package com.n1netails.n1netails.slack.model;
 
+import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
+import com.n1netails.n1netails.slack.model.block.ImageBlock;
+import com.n1netails.n1netails.slack.model.block.TextBlock;
+
 import java.util.List;
 
+/**
+ * Represents a node in a Slack message composition hierarchy.
+ * <p>
+ * All Slack blocks and elements implement this interface to participate
+ * in a tree-like structure for compositional validation and traversal.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * SlackNode block = TextBlock.of("Hello Slack!");
+ * List<SlackNode> children = block.getChildren(); // returns an empty list
+ * }</pre>
+ *
+ * <p>Implementations should be immutable wherever possible.</p>
+ *
+ * @author Artur SLimak
+ */
 public interface SlackNode {
+    /**
+     * Returns the children of this node in the Slack composition tree.
+     * <p>
+     * For leaf nodes (e.g., {@link TextBlock}, {@link GifBlock}, {@link ImageBlock}, {@link ButtonElement}),
+     * this method returns an empty list.
+     * </p>
+     *
+     * @return a list of child {@link SlackNode} instances
+     */
     List<SlackNode> getChildren();
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
index 0d8e56c..abda41f 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/actions_element/ButtonElement.java
@@ -7,6 +7,24 @@
 
 import java.util.List;
 
+/**
+ * Represents a Slack button element.
+ * <p>
+ * A button can either trigger an action (actionId) or open a link (url).
+ * Use the static factory methods {@link #link(String, String)} or {@link #action(String, String)}
+ * or the {@link Builder} for custom construction.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * ButtonElement linkButton = ButtonElement.link("Open Website", "https://example.com");
+ * ButtonElement actionButton = ButtonElement.action("Click Me", "action_123");
+ * }</pre>
+ *
+ * <p>Converts to Slack API block element via {@link #toBlockElement()}.</p>
+ *
+ * @author Artur Slimak
+ */
 @Getter
 public class ButtonElement implements SlackElement {
     private final String text;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
index a97a551..eb7df98 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ActionsBlock.java
@@ -3,12 +3,34 @@
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackElement;
 import com.n1netails.n1netails.slack.model.SlackNode;
+import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.slack.api.model.block.LayoutBlock;
 import lombok.Getter;
 
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Represents a Slack Actions Block.
+ * <p>
+ * An Actions Block contains a set of interactive elements, such as {@link ButtonElement}.
+ * Use {@link #of(List)} or {@link #builder()} to create instances.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * ActionsBlock block = ActionsBlock.builder()
+ *     .addElement(ButtonElement.link("Open", "https://example.com"))
+ *     .addElement(ButtonElement.action("Click", "action_123"))
+ *     .build();
+ * }</pre>
+ *
+ * <p>Converts to Slack API block via {@link #toLayoutBlock()}.</p>
+ *
+ * <p>Children elements can be retrieved using {@link #getChildren()}.</p>
+ *
+ * @author Artur Slimak
+ */
 @Getter
 public class ActionsBlock implements SlackBlock {
 
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
index ab57d0a..88718b9 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
@@ -8,6 +8,30 @@
 
 import java.util.List;
 
+/**
+ * Represents a Slack Image Block containing a GIF.
+ * <p>
+ * This block displays a GIF in a Slack message. Use {@link #of(String, String)} or the {@link Builder}
+ * to create instances. The GIF URL must be publicly accessible, and altText provides a description
+ * for accessibility and fallback display.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * GifBlock gif = GifBlock.of(
+ *     "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
+ *     "Funny dancing cat"
+ * );
+ * }</pre>
+ *
+ * <p>Converts to a Slack API {@link LayoutBlock} via {@link #toLayoutBlock()}.</p>
+ *
+ * <p>This block does not contain child nodes, so {@link #getChildren()} returns an empty list.</p>
+ *
+ * <p>All instances are immutable once created.</p>
+ *
+ * @author Artur Slimak
+ */
 @Getter
 public class GifBlock implements SlackBlock {
     private final String gifUrl;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
index 67d4719..606770e 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
@@ -8,7 +8,29 @@
 
 import java.util.List;
 
-
+/**
+ * Represents a Slack Image Block.
+ * <p>
+ * An Image Block displays an image in a Slack message with an alternative text for accessibility.
+ * Use {@link #of(String, String)} or the {@link Builder} to create instances.
+ * </p>
+ *
+ * Example usage:
+ * <pre>{@code
+ * ImageBlock image = ImageBlock.of(
+ *     "https://example.com/image.png",
+ *     "Descriptive alt text"
+ * );
+ * }</pre>
+ *
+ * <p>Converts to a Slack API {@link LayoutBlock} via {@link #toLayoutBlock()}.</p>
+ *
+ * <p>This block does not contain child nodes, so {@link #getChildren()} returns an empty list.</p>
+ *
+ * <p>All instances are immutable once created.</p>
+ *
+ * @author Artur Slimak
+ */
 @Getter
 public class ImageBlock implements SlackBlock {
     private final String imageUrl;
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
index 5af9784..1a29f33 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
@@ -9,6 +9,26 @@
 
 import java.util.List;
 
+/**
+ * Represents a Slack Text Block (Section Block) containing plain text.
+ * <p>
+ * Use {@link #of(String)} or the {@link Builder} to create instances.
+ * This block displays text in a Slack message and does not support child nodes.
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * TextBlock block = TextBlock.of("Hello, Slack!");
+ * }</pre>
+ *
+ * <p>Converts to a Slack API {@link LayoutBlock} via {@link #toLayoutBlock()}.</p>
+ *
+ * <p>All instances are immutable once created.</p>
+ *
+ * <p>{@link #getChildren()} always returns an empty list.</p>
+ *
+ * @author Artur Slimak
+ */
 @Getter
 public class TextBlock implements SlackBlock {
     private final String text;
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index ce84f1b..13516c7 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -1,5 +1,6 @@
 package com.n1netails.n1netails.slack.validation;
 
+import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.n1netails.n1netails.slack.model.block.ActionsBlock;
 import com.n1netails.n1netails.slack.model.block.GifBlock;
@@ -14,6 +15,24 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Registry of basic Slack validators for common blocks and elements.
+ * <p>
+ * Provides automatic validation of:
+ * <ul>
+ *     <li>{@link ImageBlock}</li>
+ *     <li>{@link GifBlock}</li>
+ *     <li>{@link TextBlock}</li>
+ *     <li>{@link ActionsBlock}</li>
+ *     <li>...</li>
+ * </ul>
+ * Can be extended with custom validators for additional Slack nodes.
+ * </p>
+ *
+ * <p>Validation is skipped if the target is {@code null} or no validator exists for its type.</p>
+ *
+ * @author Artur Slimak
+ */
 public class BasicSlackValidators {
     private final Map<Class<?>, SlackValidator<?>> validators = new HashMap<>();
 
@@ -30,6 +49,17 @@ private void init() {
         validators.put(ButtonElement.class, new ButtonElementValidator());
     }
 
+    /**
+     * Validates the given target using the registered validator for its type.
+     * <p>
+     * If no validator exists for the target type, or the target is {@code null}, validation is skipped.
+     * </p>
+     *
+     * @param <T> the type of object to validate
+     * @param target the object to validate
+     * @throws SlackValidationException if validation fails
+     */
+    @SuppressWarnings("unchecked")
     public <T> void validate(T target) {
         if (target == null) return;
         SlackValidator<T> validator = (SlackValidator<T>) validators.get(target.getClass());
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
index bf33d41..b01cc3b 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
@@ -8,6 +8,36 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Validates the blocks of a {@link SlackMessage}.
+ * <p>
+ * This validator iterates over all {@link SlackBlock} instances in a message and validates
+ * each block and its children recursively using {@link BasicSlackValidators}.
+ * </p>
+ *
+ * <p>Validation rules:</p>
+ * <ul>
+ *     <li>If {@link SlackMessage#getRawBlocks()} is non-empty, validation is skipped.</li>
+ *     <li>If {@link SlackMessage#getBlocks()} is empty or null, validation is skipped.</li>
+ *     <li>All blocks and child elements are validated using their respective {@link SlackValidator} implementations.</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * SlackMessage message = SlackMessage.builder()
+ *     .channel("general")
+ *     .addBlock(TextBlock.of("Hello!"))
+ *     .build();
+ *
+ * SlackBlockValidator validator = new SlackBlockValidator();
+ * validator.validateMessageBlocks(message); // throws SlackValidationException if invalid
+ * }</pre>
+ *
+ * <p>Throws {@link SlackValidationException} if any block or child node fails validation,
+ * with detailed error messages including the block path in the message.</p>
+ *
+ * @author Artur Slimak
+ */
 public class SlackBlockValidator {
 
     private final BasicSlackValidators basicSlackValidators;
@@ -16,6 +46,15 @@ public SlackBlockValidator() {
         this.basicSlackValidators = new BasicSlackValidators();
     }
 
+    /**
+     * Validates all {@link SlackBlock} instances in the given Slack message.
+     * <p>
+     * Validation is recursive: all child nodes of blocks are also validated.
+     * </p>
+     *
+     * @param message the Slack message to validate
+     * @throws SlackValidationException if any block or child node fails validation
+     */
     public void validateMessageBlocks(SlackMessage message) {
         if (message.getRawBlocks() != null && !message.getRawBlocks().isEmpty()) {
             return;
@@ -39,6 +78,13 @@ public void validateMessageBlocks(SlackMessage message) {
         }
     }
 
+    /**
+     * Recursively validates a {@link SlackNode} and its children, collecting any validation errors.
+     *
+     * @param node the node to validate
+     * @param path the path of the node in the message (for error reporting)
+     * @param errors the list to collect validation error messages
+     */
     private void validateNode(SlackNode node, String path, List<String> errors) {
         try {
             basicSlackValidators.validate(node);
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java
index d5b9091..c204a6b 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/SlackValidator.java
@@ -2,6 +2,27 @@
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
 
+/**
+ * Generic interface for validating Slack nodes or elements.
+ * <p>
+ * Implementations provide type-specific validation logic for Slack blocks or elements.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * SlackValidator<TextBlock> validator = new TextBlockValidator();
+ * validator.validate(TextBlock.of("Hello"));
+ * }</pre>
+ *
+ * @param <T> the type of object to validate
+ * @author Artur Slimak
+ */
 public interface SlackValidator<T> {
+    /**
+     * Validates the given target object.
+     *
+     * @param target the object to validate
+     * @throws SlackValidationException if validation fails
+     */
     void validate(T target) throws SlackValidationException;
 }
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
index c7bf0bf..35f6763 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ActionsBlockValidator.java
@@ -6,6 +6,24 @@
 import com.n1netails.n1netails.slack.validation.BasicSlackValidators;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
+/**
+ * Validator for {@link ActionsBlock}.
+ * <p>
+ * Ensures that an {@link ActionsBlock} contains at least one child element.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ActionsBlock block = ActionsBlock.builder()
+ *     .addElement(ButtonElement.link("Click me", "https://example.com"))
+ *     .build();
+ * new ActionsBlockValidator().validate(block); // passes validation
+ * }</pre>
+ *
+ * <p>Throws {@link SlackValidationException} if the block is empty.</p>
+ *
+ * @author Artur Slimak
+ */
 public class ActionsBlockValidator implements SlackValidator<ActionsBlock> {
     @Override
     public void validate(ActionsBlock target) throws SlackValidationException {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java
index 9678da3..416122f 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/GifBlockValidator.java
@@ -4,6 +4,22 @@
 import com.n1netails.n1netails.slack.model.block.GifBlock;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
+/**
+ * Validator for {@link GifBlock}.
+ * <p>
+ * Ensures that a GIF block has both a valid URL and alternative text for accessibility.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * GifBlock gif = GifBlock.of("https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif", "Dancing cat");
+ * new GifBlockValidator().validate(gif); // passes validation
+ * }</pre>
+ *
+ * <p>Throws {@link SlackValidationException} if the GIF URL or alt text is missing or blank.</p>
+ *
+ * @author Artur Slimak
+ */
 public class GifBlockValidator implements SlackValidator<GifBlock> {
     @Override
     public void validate(GifBlock target) throws SlackValidationException {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java
index e67ba0c..0db2ef7 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/ImageBlockValidator.java
@@ -4,6 +4,22 @@
 import com.n1netails.n1netails.slack.model.block.ImageBlock;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
+/**
+ * Validator for {@link ImageBlock}.
+ * <p>
+ * Ensures that an image block has both a valid URL and alternative text for accessibility.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ImageBlock image = ImageBlock.of("https://example.com/image.png", "Descriptive alt text");
+ * new ImageBlockValidator().validate(image); // passes validation
+ * }</pre>
+ *
+ * <p>Throws {@link SlackValidationException} if the image URL or alt text is missing or blank.</p>
+ *
+ * @author Artur Slimak
+ */
 public class ImageBlockValidator implements SlackValidator<ImageBlock> {
     @Override
     public void validate(ImageBlock target) throws SlackValidationException {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java
index 1ffb414..4e4fed3 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/block/TextBlockValidator.java
@@ -1,9 +1,26 @@
 package com.n1netails.n1netails.slack.validation.impl.block;
 
 import com.n1netails.n1netails.slack.exception.SlackValidationException;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
 import com.n1netails.n1netails.slack.model.block.TextBlock;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
+/**
+ * Validator for {@link TextBlock}.
+ * <p>
+ * Ensures that a text block contains non-empty text.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * TextBlock text = TextBlock.of("Hello Slack!");
+ * new TextBlockValidator().validate(text); // passes validation
+ * }</pre>
+ *
+ * <p>Throws {@link SlackValidationException} if the text is null or blank.</p>
+ *
+ * @author Artur Slimak
+ */
 public class TextBlockValidator implements SlackValidator<TextBlock> {
     @Override
     public void validate(TextBlock target) throws SlackValidationException {
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
index 67ea6ef..36f1612 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/impl/element/ButtonElementValidator.java
@@ -4,6 +4,29 @@
 import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.n1netails.n1netails.slack.validation.SlackValidator;
 
+/**
+ * Validator for {@link ButtonElement}.
+ * <p>
+ * Ensures that a button element has valid text and either an {@code actionId} or a URL.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ButtonElement button = ButtonElement.link("Visit Site", "https://example.com");
+ * new ButtonElementValidator().validate(button); // passes validation
+ *
+ * ButtonElement actionButton = ButtonElement.action("Click me", "action_123");
+ * new ButtonElementValidator().validate(actionButton); // passes validation
+ * }</pre>
+ *
+ * <p>Throws {@link SlackValidationException} if:</p>
+ * <ul>
+ *     <li>Text is null or blank</li>
+ *     <li>Both {@code actionId} and {@code url} are missing or blank</li>
+ * </ul>
+ *
+ * @author Artur Slimak
+ */
 public class ButtonElementValidator implements SlackValidator<ButtonElement> {
     @Override
     public void validate(ButtonElement target) throws SlackValidationException {

From e5b59267388cbe1e7252ffad4cf1e45aacfc73bd Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Mon, 23 Feb 2026 22:14:15 +0100
Subject: [PATCH 33/37] update readme

---
 readme.md | 73 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 50 insertions(+), 23 deletions(-)

diff --git a/readme.md b/readme.md
index ecfbde9..87db057 100644
--- a/readme.md
+++ b/readme.md
@@ -52,34 +52,55 @@ Here's how to use the client to send a message, pics or gifs:
 ```java
 import com.n1netails.n1netails.slack.api.SlackClient;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.model.block.GifBlock;
+import com.n1netails.n1netails.slack.model.actions_element.ButtonElement;
 import com.n1netails.n1netails.slack.model.block.TextBlock;
+import com.n1netails.n1netails.slack.model.block.ImageBlock;
+import com.n1netails.n1netails.slack.model.block.GifBlock;
+import com.n1netails.n1netails.slack.model.block.ActionsBlock;
+import com.n1netails.n1netails.slack.model.element.ButtonElement;
+import com.n1netails.n1netails.slack.exception.SlackClientException;
 
 public class Example {
     public static void main(String[] args) {
         // Your bot token
         String token = "xoxb-your-bot-token";
 
-        // The channel you want to send the message to (e.g., "#general")
-        String channel = "#prototype"; // or "#channel-name"
+        // Channel to send the message to
+        String channel = "#prototype";
 
-        // Use builder to create a client
-        SlackClient client = SlackClient.builder().token(token).build();
+        // Build the Slack client
+        SlackClient slackClient = SlackClient.builder()
+                .token(token)
+                .build();
 
-        // Create the message
+        // Build an ActionsBlock
+        ActionsBlock actionsBlock = ActionsBlock.builder()
+                .addElement(ButtonElement.link("Visit Website", "https://example.com"))
+                .addElement(ButtonElement.builder().text("Click me").actionId("YOUR ACTION ID").build()) //Elements support 2 types of creation
+                .build();
+
+        // Build the Slack message
         SlackMessage message = SlackMessage.builder()
-                .channel("test")
-                .text("New content 🚀") //Remember if use ANY blocks this text becomes a fallback message for notifications
-                .addBlock(new TextBlock("New content 🚀"))
-                .addBlock(new ImageBlock("YOUR IMG LINK", "YOUR ALT TEXT"))
-                .addBlock(new GifBlock("YOUR GIF LINK", "YOUR ALT TEXT"))
+                .channel(channel)
+                .text("New content 🚀") // fallback message for notifications
+                .addBlock(TextBlock.builder().text("New content 🚀").build())
+                .addBlock(ImageBlock.builder()
+                        .imageUrl("YOUR IMG LINK")
+                        .altText("YOUR ALT TEXT")
+                        .build())
+                .addBlock(ImageBlock.of("YOUR IMG LINK", "YOUR ALT TEXT")) //Blocks support 2 types of creation
+                .addBlock(GifBlock.builder()
+                        .gifUrl("YOUR GIF LINK")
+                        .altText("YOUR ALT TEXT")
+                        .build())
+                .addBlock(actionsBlock) // add the actions block with buttons
                 .build();
 
         try {
             // Send the message
             slackClient.sendMessage(message);
             System.out.println("Message sent successfully!");
-        } catch (Exception e) {
+        } catch (SlackClientException e) {
             System.err.println("Error sending message: " + e.getMessage());
         }
     }
@@ -91,32 +112,38 @@ You can also send more complex messages using [Slack's Block Kit](https://api.sl
 
 ```java
 import com.n1netails.n1netails.slack.api.SlackClient;
-import com.n1netails.n1netails.slack.api.SlackClientImpl;
 import com.n1netails.n1netails.slack.model.SlackMessage;
-import com.n1netails.n1netails.slack.api.BotService;
 import com.slack.api.model.block.Blocks;
 import com.slack.api.model.block.composition.BlockCompositions;
+import com.n1netails.n1netails.slack.exception.SlackClientException;
 
-import java.util.Arrays;
+import java.util.List;
 
 public class AdvancedExample {
     public static void main(String[] args) {
         String token = "xoxb-your-bot-token";
         String channel = "#prototype";
 
-        SlackClient client = SlackClient.builder().token(token).build();
+        // Build the Slack client
+        SlackClient slackClient = SlackClient.builder()
+                .token(token)
+                .build();
 
-        SlackMessage message = new SlackMessage();
-        message.setChannel(channel);
-        message.setText("This is a fallback message for notifications.");
-        message.setBlocks(Arrays.asList(
-                Blocks.section(section -> section.text(BlockCompositions.markdownText("*This is a message with blocks.*")))
-        ));
+        // Build a Slack message with custom Block Kit blocks
+        SlackMessage message = SlackMessage.builder()
+                .channel(channel)
+                .text("This is a fallback message for notifications.") // fallback
+                .addRawBlock(
+                        Blocks.section(section ->
+                                section.text(BlockCompositions.markdownText("*This is a message with custom blocks.*"))
+                        )
+                )
+                .build();
 
         try {
             slackClient.sendMessage(message);
             System.out.println("Advanced message sent successfully!");
-        } catch (Exception e) {
+        } catch (SlackClientException e) {
             System.err.println("Error sending message: " + e.getMessage());
         }
     }

From d9b1cb7ad9f092b361537b77ac66a2ea4fbba89b Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Tue, 24 Feb 2026 07:49:19 +0100
Subject: [PATCH 34/37] version update

---
 pom.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pom.xml b/pom.xml
index 25663ed..88cca8f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -4,7 +4,7 @@
 
   <groupId>com.n1netails</groupId>
   <artifactId>n1netails-slack-client</artifactId>
-  <version>0.2.0</version>
+  <version>0.3.0</version>
   <packaging>jar</packaging>
 
   <name>n1netails-slack-client</name>

From 7adf549c6c8e00acec7673df6f0415f7c073d590 Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Fri, 27 Feb 2026 21:25:13 +0100
Subject: [PATCH 35/37] readme updated with contributors

---
 readme.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/readme.md b/readme.md
index 87db057..f89f47f 100644
--- a/readme.md
+++ b/readme.md
@@ -184,4 +184,10 @@ For community users, open an issue on GitHub or Join our Discord
 
 ## Contributing
 
-Please use the following guidelines for contributions [CONTRIBUTING](./contributing.md)
\ No newline at end of file
+Please use the following guidelines for contributions [CONTRIBUTING](./contributing.md)
+
+## N1netails Slack Client Contributors
+
+Thanks to all the amazing people who contributed to N1netails Slack Client! 💙
+
+[![Contributors](https://contrib.rocks/image?repo=n1netails/n1netails-slack-client)](https://github.com/n1netails/n1netails-slack-client/graphs/contributors)
\ No newline at end of file

From 742c409b9a907a60427c7fa72f7a87fa4dca678d Mon Sep 17 00:00:00 2001
From: shahidfoy <shahidfoy@gmail.com>
Date: Sat, 28 Feb 2026 11:32:39 -0700
Subject: [PATCH 36/37] updating readme fixing missing builders for gif image
 and text

---
 pom.xml                                           |  2 +-
 readme.md                                         | 15 ++++++++-------
 .../n1netails/slack/model/block/GifBlock.java     |  4 ++++
 .../n1netails/slack/model/block/ImageBlock.java   |  7 +++++--
 .../n1netails/slack/model/block/TextBlock.java    |  5 ++++-
 5 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/pom.xml b/pom.xml
index 88cca8f..275e25e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -65,7 +65,7 @@
     <dependency>
       <groupId>com.slack.api</groupId>
       <artifactId>slack-api-client</artifactId>
-      <version>1.45.4</version>
+      <version>1.47.0</version>
     </dependency>
   </dependencies>
 
diff --git a/readme.md b/readme.md
index f89f47f..9d750dd 100644
--- a/readme.md
+++ b/readme.md
@@ -37,13 +37,13 @@ Install the slack client by adding the following dependency:
 <dependency>
     <groupId>com.n1netails</groupId>
     <artifactId>n1netails-slack-client</artifactId>
-    <version>0.2.0</version>
+    <version>0.3.0</version>
 </dependency>
 ```
 
 Gradle (Groovy)
 ```groovy
-implementation 'com.n1netails:n1netails-slack-client:0.2.0'
+implementation 'com.n1netails:n1netails-slack-client:0.3.0'
 ```
 
 ## Usage
@@ -79,19 +79,20 @@ public class Example {
                 .addElement(ButtonElement.builder().text("Click me").actionId("YOUR ACTION ID").build()) //Elements support 2 types of creation
                 .build();
 
+        // Build the Slack message
         // Build the Slack message
         SlackMessage message = SlackMessage.builder()
                 .channel(channel)
                 .text("New content 🚀") // fallback message for notifications
                 .addBlock(TextBlock.builder().text("New content 🚀").build())
                 .addBlock(ImageBlock.builder()
-                        .imageUrl("YOUR IMG LINK")
-                        .altText("YOUR ALT TEXT")
+                        .imageUrl("https://n1netails.com/img/n1netails_icon_transparent.png")
+                        .altText("N1netails token")
                         .build())
-                .addBlock(ImageBlock.of("YOUR IMG LINK", "YOUR ALT TEXT")) //Blocks support 2 types of creation
+                .addBlock(ImageBlock.of("https://n1netails.com/img/quickstart/n1netails-letter.jpg", "N1netails letter")) //Blocks support 2 types of creation
                 .addBlock(GifBlock.builder()
-                        .gifUrl("YOUR GIF LINK")
-                        .altText("YOUR ALT TEXT")
+                        .gifUrl("https://media1.giphy.com/media/v1.Y2lkPTc5MGI3NjExaDRhOWtpMnVsM2NiMzJ4aXpoOXpuamZzcHpudG4zbzIzenVlaHN0eSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/xsE65jaPsUKUo/giphy.gif")
+                        .altText("Fox GIF")
                         .build())
                 .addBlock(actionsBlock) // add the actions block with buttons
                 .build();
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
index 88718b9..b322ef5 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/GifBlock.java
@@ -57,6 +57,10 @@ public LayoutBlock toLayoutBlock() {
                 ;
     }
 
+    public static Builder builder() {
+        return new Builder();
+    }
+
     @Override
     public List<SlackNode> getChildren() {
         return List.of();
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
index 606770e..31afb49 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/ImageBlock.java
@@ -1,6 +1,5 @@
 package com.n1netails.n1netails.slack.model.block;
 
-import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.LayoutBlock;
@@ -41,7 +40,7 @@ private ImageBlock(String imageUrl, String altText) {
         this.altText = altText;
     }
 
-    public ImageBlock of(String imageUrl, String altText) {
+    public static ImageBlock of(String imageUrl, String altText) {
         return new ImageBlock(imageUrl, altText);
     }
 
@@ -56,6 +55,10 @@ public LayoutBlock toLayoutBlock() {
                 ;
     }
 
+    public static Builder builder() {
+        return new Builder();
+    }
+
     @Override
     public List<SlackNode> getChildren() {
         return List.of();
diff --git a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
index 1a29f33..4aca9eb 100644
--- a/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
+++ b/src/main/java/com/n1netails/n1netails/slack/model/block/TextBlock.java
@@ -1,6 +1,5 @@
 package com.n1netails.n1netails.slack.model.block;
 
-import com.n1netails.n1netails.slack.exception.SlackValidationException;
 import com.n1netails.n1netails.slack.model.SlackBlock;
 import com.n1netails.n1netails.slack.model.SlackNode;
 import com.slack.api.model.block.LayoutBlock;
@@ -48,6 +47,10 @@ public LayoutBlock toLayoutBlock() {
                 .build();
     }
 
+    public static Builder builder() {
+        return new Builder();
+    }
+
     @Override
     public List<SlackNode> getChildren() {
         return List.of();

From 611f2d211663fb9a19cb8c4f7131e1daf273c28b Mon Sep 17 00:00:00 2001
From: ArturSlimac <artur.nenakhov@student.hogent.be>
Date: Sun, 1 Mar 2026 19:07:07 +0100
Subject: [PATCH 37/37] fixing some small building errors

---
 pom.xml                                           | 15 +++++++++++----
 .../slack/api/builder/SlackBlockBuilder.java      |  2 +-
 .../slack/validation/BasicSlackValidators.java    |  4 +++-
 .../slack/validation/SlackBlockValidator.java     |  4 ++--
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/pom.xml b/pom.xml
index 275e25e..9863220 100644
--- a/pom.xml
+++ b/pom.xml
@@ -21,9 +21,16 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
+              <version>3.15.0</version>
                 <configuration>
-                    <source>17</source>
-                    <target>17</target>
+                  <release>17</release>
+                  <annotationProcessorPaths>
+                    <path>
+                      <groupId>org.projectlombok</groupId>
+                      <artifactId>lombok</artifactId>
+                      <version>1.18.42</version>
+                    </path>
+                  </annotationProcessorPaths>
                 </configuration>
             </plugin>
         </plugins>
@@ -50,8 +57,8 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>1.8</maven.compiler.source>
-    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
   </properties>
 
   <dependencies>
diff --git a/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java b/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
index 6308bc3..f5bc6f0 100644
--- a/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
+++ b/src/main/java/com/n1netails/n1netails/slack/api/builder/SlackBlockBuilder.java
@@ -27,12 +27,12 @@ public class SlackBlockBuilder {
      * Builds a list of {@link LayoutBlock}s from a {@link SlackMessage}.
      * <p>
      * Priority order:
+     * </p>
      * <ol>
      *     <li>If {@code rawBlocks} are present in the message, return them as-is.</li>
      *     <li>If {@code blocks} are present, convert each {@link SlackBlock} to {@link LayoutBlock}.</li>
      *     <li>If neither is present, returns {@code null}.</li>
      * </ol>
-     * </p>
      *
      * @param message the Slack message to convert; must not be null
      * @return list of {@link LayoutBlock}s or {@code null} if none are available
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
index 13516c7..8dfa740 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/BasicSlackValidators.java
@@ -19,6 +19,7 @@
  * Registry of basic Slack validators for common blocks and elements.
  * <p>
  * Provides automatic validation of:
+ * </p>
  * <ul>
  *     <li>{@link ImageBlock}</li>
  *     <li>{@link GifBlock}</li>
@@ -26,6 +27,7 @@
  *     <li>{@link ActionsBlock}</li>
  *     <li>...</li>
  * </ul>
+ * <p>
  * Can be extended with custom validators for additional Slack nodes.
  * </p>
  *
@@ -55,7 +57,7 @@ private void init() {
      * If no validator exists for the target type, or the target is {@code null}, validation is skipped.
      * </p>
      *
-     * @param <T> the type of object to validate
+     * @param <T>    the type of object to validate
      * @param target the object to validate
      * @throws SlackValidationException if validation fails
      */
diff --git a/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java b/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
index b01cc3b..38dfc10 100644
--- a/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
+++ b/src/main/java/com/n1netails/n1netails/slack/validation/SlackBlockValidator.java
@@ -17,8 +17,8 @@
  *
  * <p>Validation rules:</p>
  * <ul>
- *     <li>If {@link SlackMessage#getRawBlocks()} is non-empty, validation is skipped.</li>
- *     <li>If {@link SlackMessage#getBlocks()} is empty or null, validation is skipped.</li>
+ *     <li>If {@link SlackMessage#rawBlocks} is non-empty, validation is skipped.</li>
+ *     <li>If {@link SlackMessage#blocks} is empty or null, validation is skipped.</li>
  *     <li>All blocks and child elements are validated using their respective {@link SlackValidator} implementations.</li>
  * </ul>
  *