# Evercatch Java SDK

Official Java SDK for [Evercatch](https://evercatch.dev) — webhook infrastructure platform.

---

## Tech Stack

| Layer | Technology |
| :--- | :--- |
| Language | Java 11+ |
| HTTP client | OkHttp 4 |
| JSON | Gson |
| Build | Maven / Gradle |
| Spring Boot | Auto-configuration (optional) |

---

## Installation

### Maven

```xml
<dependency>
    <groupId>dev.evercatch</groupId>
    <artifactId>evercatch-java</artifactId>
    <version>1.0.0</version>
</dependency>
```

### Gradle

```gradle
implementation 'dev.evercatch:evercatch-java:1.0.0'
```

---

## 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.

**Branch format:** `EC-ID-short-description`
**Commit format:** `EC-00: type(scope): message`

See [Evercatch Org README](https://git.psmattas.com/Evercatch) for full conventions.

---

## CI/CD

Automated via Jenkins. Merges to `main` trigger staging deployments.

| Pipeline | Status |
| :--- | :---: |
| Build | ![Build Status](https://img.shields.io/badge/build-pending-lightgrey) |
| Lint | ![Lint Status](https://img.shields.io/badge/lint-pending-lightgrey) |
| Test | ![Test Status](https://img.shields.io/badge/tests-pending-lightgrey) |

---

## License

**Copyright © 2026 Evercatch.**
Proprietary and confidential. Unauthorised distribution is strictly prohibited.