Merge branch 'develop' into dependabot/maven/org.apache.maven.plugins-maven-source-plugin-3.3.1

tcheeric · web-flow · commit c8a9e9f574ec · 2025-08-13T00:20:58.000+01:00
diff --git a/.github/workflows/publish-github-packages.yml b/.github/workflows/publish-github-packages.yml
@@ -0,0 +1,31 @@
+name: Publish to GitHub Packages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**/pom.xml'
+      - '.github/workflows/publish-github-packages.yml'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+          cache: 'maven'
+          server-id: github
+          server-username: ${{ github.actor }}
+          server-password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Publish modules
+        run: ./mvnw -B -q deploy -DskipTests -Dgpg.skip=true \
+          -DaltDeploymentRepository=github::default::https://maven.pkg.github.com/${{ github.repository }}
diff --git a/AGENTS.md b/AGENTS.md
@@ -19,6 +19,7 @@ The URL format for the NIPs is https://github.com/nostr-protocol/nips/blob/maste
 - Maintain the versions in the configuration section of the pom.xml files.
 - Always make sure that the events are compliant with the Nostr protocol specifications, and that the events are valid according to the NIP specifications.
 - Always remove unused imports
+- When creating a branch, bump up the version in the pom files to the next minor version.
 
 ## Pull Requests
 
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ Artifacts are published to GitHub Packages and can be consumed from Maven by add
 <repositories>
   <repository>
     <id>github</id>
-    <url>https://maven.pkg.github.com/OWNER/REPO</url>
+    <url>https://maven.pkg.github.com/tcheeric/nostr-java</url>
   </repository>
 </repositories>
 
@@ -43,12 +43,13 @@ Artifacts are published to GitHub Packages and can be consumed from Maven by add
 
 Authenticating to GitHub Packages is required; provide a personal access token with the appropriate scopes or `GITHUB_TOKEN` credentials. See the [GitHub Packages documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) for more details.
 
+## Publishing Modules
+
+This repository includes a [GitHub Actions workflow](.github/workflows/publish-github-packages.yml) that publishes all Maven modules to GitHub Packages. The workflow runs on pushes to `main` that modify `pom.xml` files and can also be triggered manually from the Actions tab.
+
 ## Examples
 Example usages are located in the [`nostr-java-examples`](./nostr-java-examples) module. Additional demonstrations can be found in [nostr-client](https://github.com/tcheeric/nostr-client) and [SuperConductor](https://github.com/avlo/superconductor).
 
-## Retry Support
-`SpringWebSocketClient` leverages Spring Retry so that failed WebSocket send operations are attempted up to three times with exponential backoff.
-
 ## Supported NIPs
 The API currently implements the following [NIPs](https://github.com/nostr-protocol/nips):
 - [NIP-1](https://github.com/nostr-protocol/nips/blob/master/01.md)
diff --git a/docs/CODEBASE_OVERVIEW.md b/docs/CODEBASE_OVERVIEW.md
@@ -39,24 +39,72 @@ If a relay response is not received before the timeout elapses, the client logs
 ## Retry behavior
 `SpringWebSocketClient` leverages Spring Retry so that failed send operations are retried up to three times with an exponential backoff starting at 500 ms.
 
-## Creating and sending events
-The examples module shows how to create built-in and custom events. Below is an excerpt from the examples illustrating the creation of a `TextNoteEvent`:
+## Creating custom events
+The `ExpirationEventExample` demonstrates how to build a NIP-40 expiration event with `GenericEvent` and send it using both the `StandardWebSocketClient` and the `SpringWebSocketClient`:
+
 ```java
-    private static final Identity RECIPIENT = Identity.generateRandomIdentity();
-    private static final Identity SENDER = Identity.generateRandomIdentity();
+BaseTag expirationTag = new GenericTag("expiration",
+        new ElementAttribute("param0", String.valueOf(expiration)));
+GenericEvent event = new GenericEvent(identity.getPublicKey(), Kind.TEXT_NOTE,
+        List.of(expirationTag),
+        "This message will expire at the specified timestamp and be deleted by relays.\n");
+identity.sign(event);
+```
 
-    private static GenericEvent sendTextNoteEvent() {
- 
-        List<BaseTag> tags = new ArrayList<>(List.of(new PubKeyTag(RECIPIENT.getPublicKey())));
+## Creating text note events with TextNoteEvent
+The `TextNoteEventExample` illustrates constructing a text note directly with the
+out-of-the-box `TextNoteEvent` class and sending it to a relay using the
+`StandardWebSocketClient`:
 
-        var nip01 = new NIP01(SENDER);
-        nip01.createTextNoteEvent(tags, "Hello world, I'm here on nostr-java API!")
-                .sign()
-                .send(RELAYS);
+```java
+Identity identity = Identity.generateRandomIdentity();
+TextNoteEvent event = new TextNoteEvent(identity.getPublicKey(),
+        List.<BaseTag>of(),
+        "Hello from TextNoteEvent!\n");
+identity.sign(event);
+try (StandardWebSocketClient client = new StandardWebSocketClient("ws://localhost:5555")) {
+    client.send(new EventMessage(event));
+}
+```
 
-        return nip01.getEvent();
+## Sending text events with NostrSpringWebSocketClient
+The `SpringClientTextEventExample` demonstrates using the `NIP01` helper class to
+publish a simple text note via `NostrSpringWebSocketClient`:
+
+```java
+Identity sender = Identity.generateRandomIdentity();
+NIP01 client = new NIP01(sender);
+client.setRelays(Map.of("local", "ws://localhost:5555"));
+client.createTextNoteEvent("Hello from NostrSpringWebSocketClient!\n")
+      .signAndSend();
+```
+
+## Requesting events with filters
+The `FilterExample` shows how to query a relay for events matching a set of filters.
+It builds filters for author and kind, sends them with `NIP01`, and prints each
+returned event:
+
+```java
+Identity sender = Identity.generateRandomIdentity();
+NIP01 client = new NIP01(sender);
+client.setRelays(Map.of("damus", "wss://relay.damus.io"));
+
+Filters filters = new Filters(
+        new AuthorFilter<>(new PublicKey("21ef0d8541375ae4bca85285097fba370f7e540b5a30e5e75670c16679f9d144")),
+        new KindFilter<>(Kind.TEXT_NOTE)
+);
+
+List<String> responses = client.sendRequest(filters, "filter-example-" + System.currentTimeMillis());
+var decoder = new BaseMessageDecoder<BaseMessage>();
+for (String json : responses) {
+    BaseMessage message = decoder.decode(json);
+    if (message instanceof EventMessage eventMessage) {
+        System.out.println(eventMessage.getEvent());
     }
+}
+client.close();
 ```
+
 ## Creating custom events and tags
 Custom tag types can be introduced without modifying existing core code by
 registering them with the `TagRegistry`. The registry maps tag codes to factory
diff --git a/nostr-java-api/pom.xml b/nostr-java-api/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     
diff --git a/nostr-java-base/pom.xml b/nostr-java-base/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     
diff --git a/nostr-java-client/pom.xml b/nostr-java-client/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     
diff --git a/nostr-java-crypto/pom.xml b/nostr-java-crypto/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     
diff --git a/nostr-java-encryption/pom.xml b/nostr-java-encryption/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     
diff --git a/nostr-java-event/pom.xml b/nostr-java-event/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     
diff --git a/nostr-java-examples/README.md b/nostr-java-examples/README.md
diff --git a/nostr-java-examples/pom.xml b/nostr-java-examples/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>xyz.tcheeric</groupId>
         <artifactId>nostr-java</artifactId>
-        <version>0.7.3</version>
+        <version>0.8-SNAPHOT</version>
         <relativePath>../pom.xml</relativePath>
     </parent>    
     
diff --git a/nostr-java-examples/src/main/java/nostr/examples/ExpirationEventExample.java b/nostr-java-examples/src/main/java/nostr/examples/ExpirationEventExample.java
@@ -0,0 +1,57 @@
+package nostr.examples;
+
+import java.time.Instant;
+import java.util.List;
+
+import nostr.base.ElementAttribute;
+import nostr.base.Kind;
+import nostr.client.springwebsocket.SpringWebSocketClient;
+import nostr.client.springwebsocket.StandardWebSocketClient;
+import nostr.event.BaseTag;
+import nostr.event.impl.GenericEvent;
+import nostr.event.message.EventMessage;
+import nostr.event.tag.GenericTag;
+import nostr.id.Identity;
+
+/**
+ * Example demonstrating creation of an expiration event (NIP-40) and showing
+ * how to send it with either available WebSocket client.
+ */
+public class ExpirationEventExample {
+
+    private static final String RELAY_URI = "ws://localhost:5555";
+    private static final long EXPIRATION_SECONDS = 3600; // 1 hour
+
+    private static GenericEvent createExpirationEvent() {
+        Identity identity = Identity.generateRandomIdentity();
+        long expiration = Instant.now().plusSeconds(EXPIRATION_SECONDS).getEpochSecond();
+        BaseTag expirationTag = new GenericTag("expiration",
+                new ElementAttribute("param0", String.valueOf(expiration)));
+        GenericEvent event = new GenericEvent(identity.getPublicKey(), Kind.TEXT_NOTE,
+                List.of(expirationTag),
+                "This message will expire at the specified timestamp and be deleted by relays.\n");
+        identity.sign(event);
+        return event;
+    }
+
+    private static void sendWithStandardClient(GenericEvent event) throws Exception {
+        try (StandardWebSocketClient client = new StandardWebSocketClient(RELAY_URI)) {
+            client.send(new EventMessage(event));
+        }
+    }
+
+    private static void sendWithSpringClient(GenericEvent event) throws Exception {
+        try (SpringWebSocketClient client = new SpringWebSocketClient(new StandardWebSocketClient(RELAY_URI), RELAY_URI)) {
+            client.send(new EventMessage(event));
+        }
+    }
+
+    public static void main(String[] args) throws Exception {
+        GenericEvent event = createExpirationEvent();
+        // Alternative: use the standard client instead of the Spring client. It waits for
+        // a relay response and does not automatically retry failed sends.
+        // sendWithStandardClient(event);
+        sendWithSpringClient(event);
+    }
+}
+
diff --git a/nostr-java-examples/src/main/java/nostr/examples/FilterExample.java b/nostr-java-examples/src/main/java/nostr/examples/FilterExample.java
@@ -0,0 +1,50 @@
+package nostr.examples;
+
+import java.util.List;
+import java.util.Map;
+
+import nostr.api.NIP01;
+import nostr.base.Kind;
+import nostr.base.PublicKey;
+import nostr.event.BaseMessage;
+import nostr.event.filter.AuthorFilter;
+import nostr.event.filter.Filters;
+import nostr.event.filter.KindFilter;
+import nostr.event.json.codec.BaseMessageDecoder;
+import nostr.event.message.EventMessage;
+import nostr.id.Identity;
+
+/**
+ * Demonstrates requesting events from a relay using filters for author and kind.
+ */
+public class FilterExample {
+
+    private static final String RELAY_URL = "wss://relay.damus.io";
+
+    public static void main(String[] args) throws Exception {
+        var author = new PublicKey("21ef0d8541375ae4bca85285097fba370f7e540b5a30e5e75670c16679f9d144");
+
+        var filters = new Filters(
+                new AuthorFilter<>(author),
+                new KindFilter<>(Kind.TEXT_NOTE)
+        );
+
+        var subId = "filter-example-" + System.currentTimeMillis();
+
+        Identity sender = Identity.generateRandomIdentity();
+        NIP01 client = new NIP01(sender);
+        client.setRelays(Map.of("damus", RELAY_URL));
+
+        List<String> responses = client.sendRequest(filters, subId);
+
+        var decoder = new BaseMessageDecoder<BaseMessage>();
+        for (String json : responses) {
+            BaseMessage message = decoder.decode(json);
+            if (message instanceof EventMessage eventMessage) {
+                System.out.println(eventMessage.getEvent());
+            }
+        }
+        client.close();
+    }
+}
+
diff --git a/nostr-java-examples/src/main/java/nostr/examples/SpringClientTextEventExample.java b/nostr-java-examples/src/main/java/nostr/examples/SpringClientTextEventExample.java
@@ -0,0 +1,23 @@
+package nostr.examples;
+
+import java.util.Map;
+
+import nostr.api.NIP01;
+import nostr.id.Identity;
+
+/**
+ * Example showing how to create, sign and send a text note using the
+ * {@link NIP01} helper built on top of {@link nostr.api.NostrSpringWebSocketClient}.
+ */
+public class SpringClientTextEventExample {
+
+    private static final Map<String, String> RELAYS = Map.of("local", "ws://localhost:5555");
+
+    public static void main(String[] args) {
+        Identity sender = Identity.generateRandomIdentity();
+        NIP01 client = new NIP01(sender);
+        client.setRelays(RELAYS);
+        client.createTextNoteEvent("Hello from NostrSpringWebSocketClient!\n")
+                .signAndSend();
+    }
+}
diff --git a/nostr-java-examples/src/main/java/nostr/examples/TextNoteEventExample.java b/nostr-java-examples/src/main/java/nostr/examples/TextNoteEventExample.java
diff --git a/nostr-java-id/pom.xml b/nostr-java-id/pom.xml
diff --git a/nostr-java-util/pom.xml b/nostr-java-util/pom.xml
diff --git a/pom.xml b/pom.xml
