feat: replace WebSocket with REST + polling + webhooks (0.4.0)

Replaces the WebSocket-based PortalSDK with a REST HTTP client that
mirrors the TypeScript SDK's async operation pattern.

## New architecture

- PortalClient: HTTP client using java.net.http.HttpClient (Java 17)
- AsyncOperation<T>: record { streamId, CompletableFuture<T> done }
- PollOptions: builder for polling interval/timeout/per-event callback
- StreamEvent: base event with type, index, timestamp, isTerminal()
- WebhookPayload: extends StreamEvent with streamId field

## Async operations

Methods that trigger a portal async operation return AsyncOperation<T>
immediately. Events resolve the done future via:
- Polling: client.pollUntilComplete(streamId, PollOptions.defaults())
- Webhooks: client.deliverWebhookPayload(rawBody, xPortalSignature)
  (HMAC-SHA256 verified, routed to matching CompletableFuture)

## New model classes

AuthResponseData, AuthResponseStatus, KeyHandshakeResult,
RecurringPaymentResponseContent, RecurringPaymentStatus,
InvoicePaymentResponse, PayInvoiceResponse, EventsResponse,
VersionResponse, InfoResponse, WalletInfoResponse, RequestInvoiceParams

## Removed

- PortalSDK.java (WebSocket-based)
- PortalWsClient.java
- Response.java / ResponseDeserializer.java
- command/ package (all WS request/response/notification classes)

Aligns with lib PR#171 (refactor/portal-rest: REST + polling + webhooks)

Author: portal-wheatley

README.MD

@@ -1,144 +1,132 @@
-# Portal Java SDK - Documentation
+# Portal Java SDK
 
-## Introduction
-
-A Java client for the Portal WebSocket Server, providing Nostr-based authentication and Lightning Network payment processing capabilities.
-
----
+Java SDK for the [Portal REST API](https://github.com/PortalTechnologiesInc/lib).
 
 ## Installation
 
-1. Add the Jitpack repository to your `build.gradle`:
-   ```groovy
-   repositories {
-       maven { url 'https://jitpack.io' }
-   }
-   ```
-
-   Or if you are using Maven, add the following to your `pom.xml`:
-    ```xml
-    <repository>
-        <id>jitpack.io</id>
-        <url>https://jitpack.io</url>
-    </repository>
-    ```
-
-2. Add the dependency to your `build.gradle`:
-   ```groovy
-   dependencies {
-      implementation 'com.github.PortalTechnologiesInc:java-sdk:0.3.0'
-   }
-   ```
-
-   Or if you are using Maven, add the following to your `pom.xml`:
-    ```xml
-    <dependency>
-        <groupId>com.github.PortalTechnologiesInc</groupId>
-        <artifactId>java-sdk</artifactId>
-        <version>0.3.0</version>
-    </dependency>
-    ```
-
-3. Once you're done, you may now proceed integrating the SDK into your project.
-
----
-
-## Versioning & Compatibility
-
-The Java SDK version is kept in sync with the [Portal SDK Daemon](https://hub.docker.com/r/getportal/sdk-daemon) (`getportal/sdk-daemon`).
-
-**Compatibility rule:** the `major.minor` version of the SDK must match the `major.minor` version of the SDK Daemon. The patch version (`x` in `0.3.x`) is independent and can differ — it only contains bug fixes.
-
-| SDK version | SDK Daemon version |
-|-------------|-------------------|
-| `0.3.x` | `0.3.x` |
+Add via JitPack:
 
-**Example:** SDK `0.3.0` works with `getportal/sdk-daemon:0.3.1`, but not with `getportal/sdk-daemon:0.4.0`.
-
-When upgrading to a new `major.minor`, update both the SDK dependency and the Docker image tag together.
-
-
----
-
-## Basic Usage
-
-### Initialization
-
-Create an instance of `PortalSDK` by passing the websocket endpoint of your portal server:
+```kotlin
+// settings.gradle.kts
+dependencyResolutionManagement {
+    repositories {
+        maven { url = uri("https://jitpack.io") }
+    }
+}
 
-```java
-var portalSDK = new PortalSDK(wsEndpoint);
+// build.gradle.kts
+dependencies {
+    implementation("com.github.PortalTechnologiesInc:java-sdk:0.4.0")
+}
 ```
 
-### Connecting to the server
-
-Establish the WebSocket connection, then authenticate with your token:
+## Quick Start
 
 ```java
-portalSDK.connect();
-portalSDK.authenticate(authToken);
+PortalClient client = new PortalClient(
+    "http://localhost:3000",   // portal-rest base URL
+    "your-auth-token",
+    "your-webhook-secret"      // null if you only use polling
+);
+
+// Check connectivity
+String status = client.health(); // "OK"
 ```
 
+## Async Operations
 
-### Sending a command
-
-You can send a command to the server by calling the `sendCommand` method.
+All async methods return `AsyncOperation<T>` immediately. The `done` future resolves
+when a terminal event arrives — either via webhook or polling.
 
 ```java
-portalSDK.sendCommand(request, (response, err) -> {
-    if(err != null) {
-        logger.error("error sending command: {}", err);
-        return;
-    }
-    logger.info("command sent successfully: {}", response);
-});
+// Request a single payment
+AsyncOperation<StreamEvent> op = client.requestSinglePayment(
+    mainKey,
+    List.of(),  // subkeys
+    new SinglePaymentRequestContent("Coffee", 1000, Currency.MILLISATS, null, null, null)
+);
+
+System.out.println("Stream ID: " + op.streamId());
 ```
 
-### Basic example
+### Option A — Polling (no inbound HTTP required)
 
 ```java
-portalSDK.sendCommand(new CalculateNextOccurrenceRequest("weekly", System.currentTimeMillis() / 1000), (res, err) -> {
-    if(err != null) {
-        logger.error("error calculating next occurrence: {}", err);
-        return;
-    }
-    logger.info("next occurrence: {}", res.next_occurrence());
-});
+StreamEvent result = client.pollUntilComplete(
+    op.streamId(),
+    PollOptions.defaults()
+        .intervalMs(500)
+        .timeoutMs(60_000)
+        .onEvent(event -> System.out.println("Event: " + event.type))
+);
+System.out.println("Terminal event: " + result.type);
 ```
----
-
-## Available Commands
-
-Commands are implemented as specific request classes in [`src/main/java/cc/getportal/command/request/`](./src/main/java/cc/getportal/command/request/), and used via the `sendCommand()` method of the [`PortalSDK`](./src/main/java/cc/getportal/PortalSDK.java) class.
 
-Some key available commands include:
+### Option B — Webhooks (recommended for production)
 
-- [`AuthRequest`](./src/main/java/cc/getportal/command/request/AuthRequest.java): Authenticate using a token.
-- [`KeyHandshakeUrlRequest`](./src/main/java/cc/getportal/command/request/KeyHandshakeUrlRequest.java): Get handshake URL for key and relays.
-- [`RequestSinglePaymentRequest`](./src/main/java/cc/getportal/command/request/RequestSinglePaymentRequest.java): Request a single payment.
-- [`MintCashuRequest`](./src/main/java/cc/getportal/command/request/MintCashuRequest.java): Mint Cashu tokens.
+Mount the webhook endpoint in your HTTP server. The SDK verifies the
+`X-Portal-Signature` HMAC-SHA256 header automatically.
 
-> See [`src/main/java/cc/getportal/command/request/`](./src/main/java/cc/getportal/command/request/) for all available commands and additional details.
-
-To use a command, instantiate its request class and pass it to `PortalSDK.sendCommand(...)`. The full list of commands may evolve; check the request folder for the latest options.
+```java
+// In your HTTP server's POST /portal/webhook handler:
+byte[] rawBody = request.getBody();
+String signature = request.getHeader("X-Portal-Signature");
+client.deliverWebhookPayload(rawBody, signature);
 
----
+// The done future resolves when the terminal event is delivered
+StreamEvent result = op.done().get(60, TimeUnit.SECONDS);
+```
 
-## Example Integrations
+## Other Operations
 
-- See [portal-demo](https://github.com/PortalTechnologiesInc/portal-demo) for a Kotlin example.
+```java
+// Key handshake
+AsyncOperation<KeyHandshakeResult> handshake = client.newKeyHandshakeUrl(null, false);
+KeyHandshakeResult r = client.pollUntilComplete(handshake.streamId(), PollOptions.defaults())
+    .data.get... // or use handshake.done() with webhooks
+
+// Recurring payment
+AsyncOperation<RecurringPaymentResponseContent> sub = client.requestRecurringPayment(
+    mainKey, List.of(), content
+);
+
+// Invoice request
+AsyncOperation<InvoicePaymentResponse> invoice = client.requestInvoice(
+    recipientKey, List.of(),
+    new RequestInvoiceParams(1000, Currency.MILLISATS, "Test invoice")
+);
+
+// Pay a BOLT11 invoice
+PayInvoiceResponse paid = client.payInvoice("lnbc...");
+
+// JWT
+String token = client.issueJwt(targetKey, 24);
+String key = client.verifyJwt(pubkey, token);
+
+// Profile
+Profile profile = client.fetchProfile(mainKey);
+
+// Wallet info
+WalletInfoResponse info = client.getWalletInfo();
+```
 
----
+## Versioning & Compatibility
 
-## Main API
+The Java SDK version `major.minor` must match the portal-rest (sdk-daemon) version.
+Patch versions are independent.
 
-- `PortalSDK` - Main client class
-- `PortalRequest` - Represents a request to the server
-- `PortalResponse` - Represents a response from the server
-- `PortalNotification` - Represents a notification from the server
+| Java SDK | sdk-daemon |
+|----------|------------|
+| 0.4.x    | 0.4.x      |
+| 0.3.x    | 0.3.x      |
 
----
+## Architecture
 
-## Support
+The new REST + polling/webhooks architecture replaces the previous WebSocket API:
 
-For questions or issues, see the official documentation or open an issue on the project's GitHub repository.
+- **Sync operations** return their result directly.
+- **Async operations** return `AsyncOperation<T>` with `streamId` (available immediately)
+  and `done` (`CompletableFuture<T>` that resolves on terminal event).
+- **Polling** — `pollUntilComplete(streamId, options)` loops on `GET /events/:streamId`.
+- **Webhooks** — `deliverWebhookPayload(rawBody, signature)` verifies HMAC-SHA256 and
+  resolves the matching `done` future.

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "cc.getportal"
-version = "0.3.0"
+version = "0.4.0"
 
 java {
     toolchain {
@@ -23,7 +23,7 @@ publishing {
 
             groupId = "cc.getportal"
             artifactId = "portal-java-sdk"
-            version = "0.3.0"
+            version = "0.4.0"
         }
     }
 }
@@ -40,9 +40,6 @@ dependencies {
     implementation("org.slf4j:slf4j-api:2.0.17")
     runtimeOnly("org.slf4j:slf4j-simple:2.0.17")
 
-    // WebSocket Client
-    implementation("org.java-websocket:Java-WebSocket:1.6.0")
-
     // Json serialization
     implementation("com.google.code.gson:gson:2.13.2")
 

src/main/java/cc/getportal/AsyncOperation.java

@@ -0,0 +1,9 @@
+package cc.getportal;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Wraps an async operation: the stream ID is available immediately,
+ * while the {@code done} future resolves when a terminal event arrives.
+ */
+public record AsyncOperation<T>(String streamId, CompletableFuture<T> done) {}

src/main/java/cc/getportal/PollOptions.java

@@ -0,0 +1,33 @@
+package cc.getportal;
+
+import org.jetbrains.annotations.Nullable;
+
+import java.util.function.Consumer;
+
+/**
+ * Builder-style options for polling a stream until completion.
+ */
+public class PollOptions {
+    public long intervalMs = 1000;
+    public long timeoutMs = 0; // 0 = no timeout
+    @Nullable public Consumer<StreamEvent> onEvent;
+
+    public static PollOptions defaults() {
+        return new PollOptions();
+    }
+
+    public PollOptions intervalMs(long ms) {
+        this.intervalMs = ms;
+        return this;
+    }
+
+    public PollOptions timeoutMs(long ms) {
+        this.timeoutMs = ms;
+        return this;
+    }
+
+    public PollOptions onEvent(Consumer<StreamEvent> cb) {
+        this.onEvent = cb;
+        return this;
+    }
+}