EC-21: FEAT: Added new Java package and initialized the repo

Refers Evercatch/evercatch-board#21

README.md

@@ -1,49 +1,218 @@
-# 📦 Repository Name
+# Evercatch Java SDK
 
-> Short one-line description of what this repository does.
+Official Java SDK for [Evercatch](https://evercatch.dev) — webhook infrastructure platform.
 
 ---
 
-## 🧭 Overview
-
-Describe what this service/module is responsible for within the Evercatch platform.
-
----
-
-## 🛠️ Tech Stack
+## Tech Stack
 
 | Layer | Technology |
 | :--- | :--- |
-| Language | — |
-| Framework | — |
-| Key Dependencies | — |
+| Language | Java 11+ |
+| HTTP client | OkHttp 4 |
+| JSON | Gson |
+| Build | Maven / Gradle |
+| Spring Boot | Auto-configuration (optional) |
 
 ---
 
-## 🚀 Getting Started
+## Installation
 
-### Prerequisites
+### Maven
 
-- Docker & Docker Compose
-- Node.js / Python (specify version)
+```xml
+<dependency>
+    <groupId>dev.evercatch</groupId>
+    <artifactId>evercatch-java</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
 
-### Local Development
+### Gradle
 
-```bash
-# Clone the repo
-git clone https://git.psmattas.com/Evercatch/REPO_NAME.git
-cd REPO_NAME
-
-# Copy environment variables
-cp .env.example .env
-
-# Start services
-docker compose up -d
+```gradle
+implementation 'dev.evercatch:evercatch-java:1.0.0'
 ```
 
 ---
 
-## 🌿 Branching & Commits
+## Quick Start
+
+```java
+import dev.evercatch.EvercatchClient;
+import dev.evercatch.model.*;
+import java.util.List;
+
+EvercatchClient client = new EvercatchClient("ec_live_abc123");
+
+// Create a destination
+Destination dest = client.createDestination(
+    CreateDestinationRequest.builder()
+        .name("Production")
+        .url("https://myapp.com/webhooks")
+        .providers(List.of("stripe", "sendgrid"))
+        .eventTypes(List.of("payment.*", "email.delivered"))
+        .build()
+);
+System.out.println("Created: " + dest.getId());
+
+// List events
+List<Event> events = client.listEvents(
+    ListEventsRequest.builder()
+        .provider("stripe")
+        .limit(50)
+        .build()
+);
+System.out.println("Events: " + events.size());
+
+// Check usage
+Usage usage = client.getUsage();
+System.out.println("Plan: " + usage.getPlan());
+System.out.println("Events this month: " + usage.getEventsThisMonth() + "/" + usage.getEventsLimit());
+```
+
+---
+
+## API Reference
+
+### Destinations
+
+| Method | Description |
+| :--- | :--- |
+| `createDestination(request)` | Register a new webhook destination |
+| `listDestinations()` | List all destinations |
+| `getDestination(id)` | Get a destination by ID |
+| `deleteDestination(id)` | Delete a destination |
+
+### Events
+
+| Method | Description |
+| :--- | :--- |
+| `listEvents(request)` | List events with optional filters |
+| `getEvent(id)` | Get an event by ID |
+| `replayEvent(eventId, destinationIds)` | Replay an event (Studio+ only) |
+
+### Account
+
+| Method | Description |
+| :--- | :--- |
+| `getUsage()` | Get current account usage statistics |
+
+---
+
+## Spring Boot Integration
+
+Add the dependency, then set your API key in `application.properties`:
+
+```properties
+evercatch.api-key=ec_live_abc123
+# Optional: override the default API base URL
+# evercatch.base-url=https://api.evercatch.dev/v1
+```
+
+Or in `application.yml`:
+
+```yaml
+evercatch:
+  api-key: ec_live_abc123
+```
+
+An `EvercatchClient` bean is registered automatically — inject it wherever you need it:
+
+```java
+@Service
+public class WebhookService {
+
+    private final EvercatchClient evercatch;
+
+    public WebhookService(EvercatchClient evercatch) {
+        this.evercatch = evercatch;
+    }
+
+    public void process(String eventId) throws EvercatchException {
+        Event event = evercatch.getEvent(eventId);
+        // ...
+    }
+}
+```
+
+Override the auto-configured bean by declaring your own:
+
+```java
+@Bean
+public EvercatchClient evercatchClient() {
+    return new EvercatchClient("ec_live_abc123", "https://custom-host/v1");
+}
+```
+
+---
+
+## Error Handling
+
+All methods throw `EvercatchException` (a checked exception). The status code is available via `getStatusCode()`:
+
+```java
+try {
+    client.replayEvent(eventId, List.of(destId));
+} catch (EvercatchException e) {
+    if (e.getStatusCode() == 402) {
+        System.out.println("Upgrade to Studio to replay events.");
+    } else {
+        throw e;
+    }
+}
+```
+
+---
+
+## Building from Source
+
+```bash
+# Maven
+mvn clean package
+
+# Run tests
+mvn test
+
+# Gradle
+./gradlew build
+
+# Run tests
+./gradlew test
+```
+
+---
+
+## Publishing
+
+### Maven Central
+
+```bash
+# Build, sign, and stage
+mvn clean deploy -P release
+
+# Release from staging
+mvn nexus-staging:release
+```
+
+### GitHub Packages
+
+```bash
+mvn deploy
+# or
+./gradlew publish
+```
+
+---
+
+## Requirements
+
+- Java 11 or higher
+- Maven 3.6+ or Gradle 7.0+
+
+---
+
+## Branching & Commits
 
 All work follows the Evercatch contribution guide defined in the org README.
 
@@ -54,7 +223,7 @@ See [Evercatch Org README](https://git.psmattas.com/Evercatch) for full conventi
 
 ---
 
-## ⚙️ CI/CD
+## CI/CD
 
 Automated via Jenkins. Merges to `main` trigger staging deployments.
 
@@ -66,7 +235,7 @@ Automated via Jenkins. Merges to `main` trigger staging deployments.
 
 ---
 
-## 📄 License
+## License
 
 **Copyright © 2026 Evercatch.**
 Proprietary and confidential. Unauthorised distribution is strictly prohibited.