feat: add age verification endpoints (0.4.1)

Author: portal-wheatley

README.MD

@@ -12,7 +12,7 @@ dependencyResolutionManagement {
 
 // build.gradle.kts
 dependencies {
-    implementation("com.github.PortalTechnologiesInc:java-sdk:0.4.0")
+    implementation("com.github.PortalTechnologiesInc:java-sdk:0.4.1")
 }
 ```
 
@@ -87,6 +87,22 @@ client.deliverWebhookPayload(rawBody, request.getHeader("X-Portal-Signature"));
 | `requestCashu(recipientKey, subkeys, mintUrl, unit, amount)` | `AsyncOperation<CashuResponseStatus>` |
 | `authenticateKey(mainKey, subkeys)` | `AsyncOperation<AuthResponseData>` |
 | `newKeyHandshakeUrl(staticToken, noRequest)` | `AsyncOperation<KeyHandshakeResult>` |
+| `createVerificationSession(relayUrls)` | `AsyncOperation<CashuResponseStatus>` |
+| `requestVerificationToken(recipientKey, subkeys)` | `AsyncOperation<CashuResponseStatus>` |
+
+### Age Verification
+
+```java
+// Create verification session — single call handles everything
+AsyncOperation<CashuResponseStatus> op = client.createVerificationSession();
+System.out.println("Redirect user to: " + op.sessionUrl());
+
+// Wait for the user to complete verification in their browser
+CashuResponseStatus result = client.pollUntilComplete(op, new PollOptions(1000, 300_000));
+if (result.status.equals("success")) {
+    System.out.println("Verified! Token: " + result.token);
+}
+```
 
 ## Sync methods
 

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "cc.getportal"
-version = "0.4.0"
+version = "0.4.1"
 
 java {
     toolchain {
@@ -23,7 +23,7 @@ publishing {
 
             groupId = "cc.getportal"
             artifactId = "portal-java-sdk"
-            version = "0.4.0"
+            version = "0.4.1"
         }
     }
 }

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

@@ -1,9 +1,43 @@
 package cc.getportal;
 
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
 
 /**
  * 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) {}
+public class AsyncOperation<T> {
+    private final String streamId;
+    private final CompletableFuture<T> done;
+    private final Map<String, String> metadata = new ConcurrentHashMap<>();
+
+    public AsyncOperation(String streamId, CompletableFuture<T> done) {
+        this.streamId = streamId;
+        this.done = done;
+    }
+
+    public String streamId() { return streamId; }
+    public CompletableFuture<T> done() { return done; }
+
+    public void setMetadata(String key, String value) {
+        metadata.put(key, value);
+    }
+
+    public @Nullable String getMetadata(String key) {
+        return metadata.get(key);
+    }
+
+    /** Convenience: get the session_url for verification sessions. */
+    public @Nullable String sessionUrl() {
+        return metadata.get("session_url");
+    }
+
+    /** Convenience: get the session_id for verification sessions. */
+    public @Nullable String sessionId() {
+        return metadata.get("session_id");
+    }
+}

src/main/java/cc/getportal/PortalClient.java

@@ -486,6 +486,58 @@ public WalletInfoResponse getWalletInfo() throws IOException, InterruptedExcepti
         return get("/wallet/info", WalletInfoResponse.class);
     }
 
+    // -------------------------------------------------------------------------
+    // Verification
+    // -------------------------------------------------------------------------
+
+    /**
+     * Create an age verification session and automatically start listening for the
+     * verification token. Returns session info plus an {@link AsyncOperation} that
+     * resolves when the user completes verification.
+     *
+     * <p>Redirect the user to {@code response.session_url} in their browser.
+     * Poll or await {@code done()} for the {@link CashuResponseStatus} result.
+     *
+     * @param relayUrls optional relay URLs; defaults to server's [nostr] config if null
+     */
+    public AsyncOperation<CashuResponseStatus> createVerificationSession(
+            @Nullable List<String> relayUrls
+    ) throws IOException, InterruptedException, PortalSDKException {
+        Map<String, Object> body = new java.util.HashMap<>();
+        if (relayUrls != null) body.put("relays", relayUrls);
+        VerificationSessionResponse resp = post("/verification/sessions", body, VerificationSessionResponse.class);
+        AsyncOperation<CashuResponseStatus> op = registerStream(resp.stream_id,
+                json -> gson.fromJson(json.getAsJsonObject("status"), CashuResponseStatus.class));
+        op.setMetadata("session_id", resp.session_id);
+        op.setMetadata("session_url", resp.session_url);
+        op.setMetadata("ephemeral_npub", resp.ephemeral_npub);
+        op.setMetadata("expires_at", String.valueOf(resp.expires_at));
+        return op;
+    }
+
+    /** Convenience overload with default relays. */
+    public AsyncOperation<CashuResponseStatus> createVerificationSession()
+            throws IOException, InterruptedException, PortalSDKException {
+        return createVerificationSession(null);
+    }
+
+    /**
+     * Request a verification token from a user who already holds one
+     * (e.g. verified through the mobile app).
+     *
+     * @param recipientKey hex-encoded public key of the token holder
+     * @param subkeys      optional subkeys
+     */
+    public AsyncOperation<CashuResponseStatus> requestVerificationToken(
+            String recipientKey, List<String> subkeys
+    ) throws IOException, InterruptedException, PortalSDKException {
+        Map<String, Object> body = Map.of("recipient_key", recipientKey, "subkeys", subkeys);
+        JsonObject resp = post("/verification/token", body, JsonObject.class);
+        String streamId = resp.get("stream_id").getAsString();
+        return registerStream(streamId,
+                json -> gson.fromJson(json.getAsJsonObject("status"), CashuResponseStatus.class));
+    }
+
     // -------------------------------------------------------------------------
     // Events (low-level)
     // -------------------------------------------------------------------------

src/main/java/cc/getportal/model/VerificationSessionResponse.java

@@ -0,0 +1,12 @@
+package cc.getportal.model;
+
+/**
+ * Response from {@code POST /verification/sessions}.
+ */
+public class VerificationSessionResponse {
+    public String session_id;
+    public String session_url;
+    public String ephemeral_npub;
+    public long expires_at;
+    public String stream_id;
+}