Develop

nostr-java-api/src/main/java/nostr/api/EventNostr.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.util.List;
@@ -28,7 +24,7 @@
 
   @Setter private GenericEvent event;
 
   private PublicKey recipient;
 
   public EventNostr(@NonNull Identity sender) {
     super(sender);

nostr-java-api/src/main/java/nostr/api/NIP02.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.util.List;
@@ -32,7 +28,7 @@
   @SuppressWarnings("rawtypes")
   public NIP02 createContactListEvent(List<BaseTag> pubKeyTags) {
     GenericEvent genericEvent =
         new GenericEventFactory(getSender(), Constants.Kind.CONTACT_LIST, pubKeyTags, "").create();
     updateEvent(genericEvent);
     return this;
   }

nostr-java-api/src/main/java/nostr/api/NIP03.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import lombok.NonNull;

nostr-java-api/src/main/java/nostr/api/NIP04.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.util.List;

nostr-java-api/src/main/java/nostr/api/NIP05.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import static nostr.base.IEvent.MAPPER_BLACKBIRD;

nostr-java-api/src/main/java/nostr/api/NIP12.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.net.URL;

nostr-java-api/src/main/java/nostr/api/NIP14.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.util.List;

nostr-java-api/src/main/java/nostr/api/NIP15.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.util.List;

nostr-java-api/src/main/java/nostr/api/NIP20.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import lombok.NonNull;

nostr-java-api/src/main/java/nostr/api/NIP23.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.net.URL;

nostr-java-api/src/main/java/nostr/api/NIP25.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.net.MalformedURLException;

nostr-java-api/src/main/java/nostr/api/NIP28.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import static nostr.api.NIP12.createHashtagTag;

nostr-java-api/src/main/java/nostr/api/NIP30.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import lombok.NonNull;

nostr-java-api/src/main/java/nostr/api/NIP32.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import lombok.NonNull;

nostr-java-api/src/main/java/nostr/api/NIP40.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import lombok.NonNull;

nostr-java-api/src/main/java/nostr/api/NIP42.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api;
 
 import java.util.ArrayList;

nostr-java-api/src/main/java/nostr/api/client/NostrEventDispatcher.java

@@ -18,11 +18,24 @@ public final class NostrEventDispatcher {
   private final NoteService noteService;
   private final NostrRelayRegistry relayRegistry;
 
+  /**
+   * Create a dispatcher that uses the provided services to verify and distribute events.
+   *
+   * @param noteService service responsible for communicating with relays
+   * @param relayRegistry registry that tracks the connected relay handlers
+   */
   public NostrEventDispatcher(NoteService noteService, NostrRelayRegistry relayRegistry) {
     this.noteService = noteService;
     this.relayRegistry = relayRegistry;
   }
 
+  /**
+   * Verify the supplied event and forward it to all configured relays.
+   *
+   * @param event event to send
+   * @return responses returned by relays
+   * @throws IllegalStateException if verification fails
+   */
   public List<String> send(@NonNull IEvent event) {
     if (event instanceof GenericEvent genericEvent) {
       if (!verify(genericEvent)) {
@@ -32,6 +45,13 @@ public List<String> send(@NonNull IEvent event) {
     return noteService.send(event, relayRegistry.getClientMap());
   }
 
+  /**
+   * Verify the Schnorr signature of the provided event.
+   *
+   * @param event event to verify
+   * @return {@code true} if the signature is valid
+   * @throws IllegalStateException if the event is unsigned or verification cannot complete
+   */
   public boolean verify(@NonNull GenericEvent event) {
     if (!event.isSigned()) {
       throw new IllegalStateException("The event is not signed");

nostr-java-api/src/main/java/nostr/api/client/NostrRelayRegistry.java

@@ -18,14 +18,29 @@ public final class NostrRelayRegistry {
   private final Map<String, WebSocketClientHandler> clientMap = new ConcurrentHashMap<>();
   private final WebSocketClientHandlerFactory factory;
 
+  /**
+   * Create a registry backed by the supplied handler factory.
+   *
+   * @param factory factory used to lazily create relay handlers
+   */
   public NostrRelayRegistry(WebSocketClientHandlerFactory factory) {
     this.factory = factory;
   }
 
+  /**
+   * Expose the internal handler map for read-only scenarios.
+   *
+   * @return relay name to handler map
+   */
   public Map<String, WebSocketClientHandler> getClientMap() {
     return clientMap;
   }
 
+  /**
+   * Ensure handlers exist for the provided relay definitions.
+   *
+   * @param relays mapping of relay names to relay URIs
+   */
   public void registerRelays(Map<String, String> relays) {
     for (Entry<String, String> relayEntry : relays.entrySet()) {
       clientMap.computeIfAbsent(
@@ -34,6 +49,11 @@ public void registerRelays(Map<String, String> relays) {
     }
   }
 
+  /**
+   * Take a snapshot of the currently registered relay URIs.
+   *
+   * @return immutable copy of relay name to URI mappings
+   */
   public Map<String, String> snapshotRelays() {
     return clientMap.values().stream()
         .collect(
@@ -44,20 +64,36 @@ public Map<String, String> snapshotRelays() {
                 HashMap::new));
   }
 
+  /**
+   * Return handlers that correspond to base relay connections (non request-scoped).
+   *
+   * @return list of base handlers
+   */
   public List<WebSocketClientHandler> baseHandlers() {
     return clientMap.entrySet().stream()
         .filter(entry -> !entry.getKey().contains(":"))
         .map(Entry::getValue)
         .toList();
   }
 
+  /**
+   * Retrieve handlers dedicated to the provided subscription identifier.
+   *
+   * @param subscriptionId subscription identifier suffix
+   * @return list of handlers for the subscription
+   */
   public List<WebSocketClientHandler> requestHandlers(String subscriptionId) {
     return clientMap.entrySet().stream()
         .filter(entry -> entry.getKey().endsWith(":" + subscriptionId))
         .map(Entry::getValue)
         .toList();
   }
 
+  /**
+   * Create request-scoped handlers for each base relay if they do not already exist.
+   *
+   * @param subscriptionId subscription identifier used to scope handlers
+   */
   public void ensureRequestClients(String subscriptionId) {
     for (WebSocketClientHandler baseHandler : baseHandlers()) {
       String requestKey = baseHandler.getRelayName() + ":" + subscriptionId;
@@ -67,6 +103,11 @@ public void ensureRequestClients(String subscriptionId) {
     }
   }
 
+  /**
+   * Close all handlers currently registered with the registry.
+   *
+   * @throws IOException if closing any handler fails
+   */
   public void closeAll() throws IOException {
     for (WebSocketClientHandler client : clientMap.values()) {
       client.close();

nostr-java-api/src/main/java/nostr/api/client/NostrRequestDispatcher.java

@@ -14,10 +14,22 @@ public final class NostrRequestDispatcher {
 
   private final NostrRelayRegistry relayRegistry;
 
+  /**
+   * Create a dispatcher that leverages the registry to route REQ commands.
+   *
+   * @param relayRegistry registry that owns relay handlers
+   */
   public NostrRequestDispatcher(NostrRelayRegistry relayRegistry) {
     this.relayRegistry = relayRegistry;
   }
 
+  /**
+   * Send a REQ message using the provided filters across all registered relays.
+   *
+   * @param filters filters describing the subscription
+   * @param subscriptionId subscription identifier applied to handlers
+   * @return list of relay responses
+   */
   public List<String> sendRequest(@NonNull Filters filters, @NonNull String subscriptionId) {
     relayRegistry.ensureRequestClients(subscriptionId);
     return relayRegistry.requestHandlers(subscriptionId).stream()
@@ -26,6 +38,13 @@ public List<String> sendRequest(@NonNull Filters filters, @NonNull String subscr
         .toList();
   }
 
+  /**
+   * Send REQ messages for multiple filter sets under the same subscription identifier.
+   *
+   * @param filtersList list of filter definitions to send
+   * @param subscriptionId subscription identifier applied to handlers
+   * @return distinct collection of relay responses
+   */
   public List<String> sendRequest(@NonNull List<Filters> filtersList, @NonNull String subscriptionId) {
     return filtersList.stream()
         .map(filters -> sendRequest(filters, subscriptionId))
@@ -34,6 +53,15 @@ public List<String> sendRequest(@NonNull List<Filters> filtersList, @NonNull Str
         .toList();
   }
 
+  /**
+   * Convenience helper for issuing a REQ message via a specific client instance.
+   *
+   * @param client relay client used to send the REQ
+   * @param filters filters describing the subscription
+   * @param subscriptionId subscription identifier applied to the message
+   * @return list of responses returned by the relay
+   * @throws IOException if sending fails
+   */
   public static List<String> sendRequest(
       @NonNull SpringWebSocketClient client,
       @NonNull Filters filters,

nostr-java-api/src/main/java/nostr/api/client/NostrSubscriptionManager.java

@@ -14,10 +14,24 @@ public final class NostrSubscriptionManager {
 
   private final NostrRelayRegistry relayRegistry;
 
+  /**
+   * Create a manager backed by the provided relay registry.
+   *
+   * @param relayRegistry registry used to look up relay handlers
+   */
   public NostrSubscriptionManager(NostrRelayRegistry relayRegistry) {
     this.relayRegistry = relayRegistry;
   }
 
+  /**
+   * Subscribe to the provided filters across all base relay handlers.
+   *
+   * @param filters subscription filters to apply
+   * @param subscriptionId identifier shared across relay subscriptions
+   * @param listener callback invoked for each event payload
+   * @param errorConsumer callback invoked when an error occurs
+   * @return a handle that closes all subscriptions when invoked
+   */
   public AutoCloseable subscribe(
       @NonNull Filters filters,
       @NonNull String subscriptionId,

nostr-java-api/src/main/java/nostr/api/client/WebSocketClientHandlerFactory.java

@@ -8,6 +8,15 @@
  */
 @FunctionalInterface
 public interface WebSocketClientHandlerFactory {
+  /**
+   * Create a handler for the given relay definition.
+   *
+   * @param relayName logical relay identifier
+   * @param relayUri websocket URI of the relay
+   * @return initialized handler ready for use
+   * @throws ExecutionException if the underlying client initialization fails
+   * @throws InterruptedException if thread interruption occurs during initialization
+   */
   WebSocketClientHandler create(String relayName, String relayUri)
       throws ExecutionException, InterruptedException;
 }

nostr-java-api/src/main/java/nostr/api/factory/BaseMessageFactory.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api.factory;
 
 import lombok.NoArgsConstructor;

nostr-java-api/src/main/java/nostr/api/factory/EventFactory.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api.factory;
 
 import java.util.ArrayList;

nostr-java-api/src/main/java/nostr/api/factory/MessageFactory.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api.factory;
 
 import lombok.NoArgsConstructor;

nostr-java-api/src/main/java/nostr/api/factory/impl/BaseTagFactory.java

@@ -1,7 +1,3 @@
-/*
- * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
- * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Class.java to edit this template
- */
 package nostr.api.factory.impl;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
@@ -17,7 +13,7 @@
 import nostr.event.json.codec.EventEncodingException;
 
 /**
  * Utility to create {@link BaseTag} instances from code and parameters or from JSON.
  */
 @Data
 @EqualsAndHashCode(callSuper = false)
@@ -53,6 +49,15 @@
     this.params = new ArrayList<>();
   }
 
+  /**
+   * Build the tag instance based on the factory configuration.
+   *
+   * <p>If a JSON payload was supplied, it is decoded into a {@link GenericTag}. Otherwise, a tag
+   * is built from the configured code and parameters.
+   *
+   * @return the constructed tag instance
+   * @throws EventEncodingException if the JSON payload cannot be parsed
+   */
   public BaseTag create() {
     if (jsonString != null) {
       try {