nostr 0.3.0 → 0.5.0

data/docs/getting-started/installation.md

@@ -0,0 +1,21 @@
+# Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```shell
+bundle add nostr
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```shell
+gem install nostr
+```
+
+## Requiring the gem
+
+All examples in this guide assume that the gem has been required:
+
+```ruby
+require 'nostr'
+```

data/docs/getting-started/overview.md

@@ -0,0 +1,170 @@
+---
+editLink: true
+---
+
+# Getting started
+
+This gem abstracts the complexity that you would face when trying to connect to relays web sockets, send and receive
+events, handle events callbacks and much more.
+
+## Visual overview
+
+Begin your journey with an overview of the essential functions. A visual representation below maps out the key
+components we'll delve into in this section.
+
+```mermaid
+classDiagram
+    class Client {
+        connect(relay)
+        publish(event)
+        subscribe(subscription_id, filter)
+        unsubscribe(subscription_id)
+    }
+    class Relay {
+        url
+        name
+    }
+    class Event {
+        pubkey
+        created_at
+        kind
+        tags
+        content
+        add_event_reference(event_id)
+        add_pubkey_reference(pubkey)
+        serialize()
+        to_h()
+        sign(private_key)
+    }
+    class Subscription {
+        id
+        filter
+    }
+    class Filter {
+        ids
+        authors
+        kinds
+        since
+        until
+        limit
+        to_h()
+    }
+    class EventKind {
+        <<Enumeration>>
+        SET_METADATA
+        TEXT_NOTE
+        RECOMMEND_SERVER
+        CONTACT_LIST
+        ENCRYPTED_DIRECT_MESSAGE
+    }
+    class KeyPair {
+        private_key
+        public_key
+    }
+    class Keygen {
+        generate_key_pair()
+        generate_private_key()
+        extract_public_key(private_key)
+    }
+    class User {
+        keypair
+        create_event(event_attributes)
+    }
+
+    Client --> Relay : connects via <br> WebSockets to
+    Client --> Event : uses WebSockets to <br> publish and receive
+    Client --> Subscription : receives Events via
+    Subscription --> Filter : uses
+    Event --> EventKind : is of kind
+    User --> KeyPair : has
+    User --> Event : creates and signs
+    User --> Keygen : uses to generate keys
+    Keygen --> KeyPair : generates
+```
+
+## Code overview
+
+Explore the provided code snippet to learn about initializing the Nostr [client](../core/client.md), generating
+a [keypair](../core/keys), [publishing](../relays/publishing-events) an event, and
+efficiently [managing event subscriptions](../subscriptions/creating-a-subscription) (including event reception,
+filtering, and WebSocket event handling).
+
+```ruby
+# Require the gem
+require 'nostr'
+
+# Instantiate a client
+client = Nostr::Client.new
+
+# a) Use an existing keypair
+keypair = Nostr::KeyPair.new(
+  private_key: Nostr::PrivateKey.new('your-hex-private-key'),
+  public_key: Nostr::PublicKey.new('your-hex-public-key'),
+)
+
+# b) Or build a keypair from a private key
+keygen = Nostr::Keygen.new
+keypair = keygen.get_key_pair_from_private_key(
+  Nostr::PrivateKey.new('your-hex-private-key')
+)
+
+# c) Or create a new keypair
+keygen = Nostr::Keygen.new
+keypair = keygen.generate_keypair
+
+# Create a user with the keypair
+user = Nostr::User.new(keypair: keypair)
+
+# Create a signed event
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+# Connect asynchronously to a relay
+relay = Nostr::Relay.new(url: 'wss://nostr.wine', name: 'Wine')
+client.connect(relay)
+
+# Listen asynchronously for the connect event
+client.on :connect do
+  # Send the event to the Relay
+  client.publish(text_note_event)
+
+  # Create a filter to receive the first 20 text notes
+  # and encrypted direct messages from the relay that
+  # were created in the previous hour
+  filter = Nostr::Filter.new(
+    kinds: [
+      Nostr::EventKind::TEXT_NOTE,
+      Nostr::EventKind::ENCRYPTED_DIRECT_MESSAGE
+    ],
+    since: Time.now.to_i - 3600, # 1 hour ago
+    until: Time.now.to_i,
+    limit: 20,
+  )
+
+  # Subscribe to events matching conditions of a filter
+  subscription = client.subscribe(filter: filter)
+
+  # Unsubscribe from events matching the filter above
+  client.unsubscribe(subscription.id)
+end
+
+# Listen for incoming messages and print them
+client.on :message do |message|
+  puts message
+end
+
+# Listen for error messages
+client.on :error do |error_message|
+  # Handle the error
+end
+
+# Listen for the close event
+client.on :close do |code, reason|
+  # You may attempt to reconnect to the relay here
+end
+```
+
+Beyond what's covered here, the Nostr protocol and this gem boast a wealth of additional functionalities. For an
+in-depth exploration of these capabilities, proceed to the next page.

data/docs/implemented-nips.md

@@ -0,0 +1,9 @@
+# Implemented NIPs
+
+NIPs stand for Nostr Implementation Possibilities. They exist to document what may be implemented by Nostr-compatible
+relay and client software.
+
+- [NIP-01: Basic protocol flow description](https://github.com/nostr-protocol/nips/blob/master/01.md)
+- [NIP-02: Contact List and Petnames](https://github.com/nostr-protocol/nips/blob/master/02.md)
+- [NIP-04: Encrypted Direct Message](https://github.com/nostr-protocol/nips/blob/master/04.md)
+- [NIP-19: Bech32-encoded entities](https://github.com/nostr-protocol/nips/blob/master/19.md)

data/docs/index.md

@@ -0,0 +1,44 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Nostr"
+  text: "Ruby"
+  tagline: "The Nostr protocol implemented in a Ruby gem."
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started/overview
+    - theme: alt
+      text: View on Github
+      link: https://github.com/wilsonsilva/nostr
+    - theme: alt
+      text: View on RubyDoc
+      link: https://www.rubydoc.info/gems/nostr
+    - theme: alt
+      text: View on RubyGems
+      link: https://rubygems.org/gems/nostr
+
+features:
+  - title: Asynchronous
+    details: Non-blocking I/O for maximum performance.
+    icon: ⚡
+  - title: Lightweight
+    details: Minimal runtime dependencies.
+    icon: 🪶
+  - title: Intuitive
+    details: The API mirrors the Nostr protocol specification domain language.
+    icon: 💡
+  - title: Fully documented
+    details: All code is documented from both the maintainer's as well as the consumer's perspective.
+    icon: 📚
+  - title: Fully tested
+    details: All code is tested with 100% coverage.
+    icon: 🧪
+  - title: Fully typed
+    details: All code is typed with <a href="https://rubygems.org/gems/rbs" target="_blank">RBS</a> with the help of <a href="https://rubygems.org/gems/typeprof" target="_blank">TypeProf</a>. Type correctness is enforced by <a href="https://rubygems.org/gems/steep" target="_blank">Steep</a>.
+    icon: ✅
+
+---
+

data/docs/markdown-examples.md

@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

data/docs/package.json

@@ -0,0 +1,12 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "mermaid": "^10.6.1",
+    "vitepress": "^1.0.0-rc.25",
+    "vitepress-plugin-mermaid": "^2.0.15"
+  }
+}

data/docs/relays/connecting-to-a-relay.md

@@ -0,0 +1,21 @@
+# Connecting to a Relay
+
+You must connect your nostr [Client](../core/client) to a relay in order to send and receive [Events](../events).
+Instantiate a [`Nostr::Client`](https://www.rubydoc.info/gems/nostr/Nostr/Client) and a
+[`Nostr::Relay`](https://www.rubydoc.info/gems/nostr/Nostr/Relay) giving it the `url` of your relay. The `name`
+attribute is just descriptive.
+Calling [`Client#connect`](https://www.rubydoc.info/gems/nostr/Nostr/Client#connect-instance_method) attempts to
+establish a WebSocket connection between the Client and the Relay.
+
+```ruby
+client = Nostr::Client.new
+relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
+
+# Listen for the connect event
+client.on :connect do
+  # When this block executes, you're connected to the relay
+end
+
+# Connect to a relay asynchronously
+client.connect(relay)
+```

data/docs/relays/publishing-events.md

@@ -0,0 +1,29 @@
+# Publishing events
+
+Create a [signed event](../core/keys) and call the method
+[`Nostr::Client#publish`](https://www.rubydoc.info/gems/nostr/Nostr/Client#publish-instance_method) to send the
+event to the relay.
+
+```ruby{4-8,17}
+# Create a user with the keypair
+user = Nostr::User.new(keypair: keypair)
+
+# Create a signed event
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+# Connect asynchronously to a relay
+relay = Nostr::Relay.new(url: 'wss://nostr.wine', name: 'Wine')
+client.connect(relay)
+
+# Listen asynchronously for the connect event
+client.on :connect do
+  # Send the event to the relay
+  client.publish(text_note_event)
+end
+```
+
+The relay will verify the signature of the event with the public key. If the signature is valid, the relay should
+broadcast the event to all subscribers.

data/docs/relays/receiving-events.md

@@ -0,0 +1,6 @@
+# Receiving events
+
+To receive events from Relays, you must create a subscription on the relay. A subscription is a filter that defines the
+events you want to receive.
+
+For more information, read the [Subscription](../subscriptions/creating-a-subscription.md) section.

data/docs/subscriptions/creating-a-subscription.md

@@ -0,0 +1,49 @@
+# Creating a subscription
+
+A client can request events and subscribe to new updates __after__ it has established a connection with the Relay.
+
+You may use a [`Nostr::Filter`](https://www.rubydoc.info/gems/nostr/Nostr/Filter) instance with as many attributes as
+you wish:
+
+```ruby
+client.on :connect do
+  filter = Nostr::Filter.new(
+    ids: ['8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8'],
+    authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
+    kinds: [Nostr::EventKind::TEXT_NOTE],
+    e: ["f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52"],
+    p: ["f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8"],
+    since: 1230981305,
+    until: 1292190341,
+    limit: 420,
+  )
+
+  subscription = client.subscribe(subscription_id: 'an-id', filter: filter)
+end
+```
+
+With just a few:
+
+```ruby
+client.on :connect do
+  filter = Nostr::Filter.new(kinds: [Nostr::EventKind::TEXT_NOTE])
+  subscription = client.subscribe(subscription_id: 'an-id', filter: filter)
+end
+```
+
+Or omit the filter:
+
+```ruby
+client.on :connect do
+  subscription = client.subscribe(subscription_id: 'an-id')
+end
+```
+
+Or even omit the subscription id:
+
+```ruby
+client.on :connect do
+  subscription = client.subscribe(filter: filter)
+  subscription.id # => "13736f08dee8d7b697222ba605c6fab2" (randomly generated)
+end
+```

data/docs/subscriptions/deleting-a-subscription.md

@@ -0,0 +1,10 @@
+# Stop previous subscriptions
+
+You can stop receiving messages from a subscription by calling
+[`Nostr::Client#unsubscribe`](https://www.rubydoc.info/gems/nostr/Nostr/Client#unsubscribe-instance_method) with the
+ID of the subscription you want to stop receiving messages from:
+
+```ruby
+client.unsubscribe('your-subscription-id')
+client.unsubscribe(subscription.id)
+```

data/docs/subscriptions/filtering-subscription-events.md

@@ -0,0 +1,115 @@
+# Filtering events
+
+## Filtering by id
+
+You can filter events by their ids:
+
+```ruby
+filter = Nostr::Filter.new(
+  ids: [
+    # matches events with these exact IDs
+    '8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8',
+    '461544014d87c9eaf3e76e021240007dff2c7afb356319f99c741b45749bf82f',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by author
+
+You can filter events by their author's pubkey:
+
+```ruby
+filter = Nostr::Filter.new(
+  authors: [
+    # matches events whose (authors) pubkey match these exact IDs
+    'b698043170d580f8ae5bad4ac80b1fdb508e957f0bbffe97f2a8915fa8b34070',
+    '51f853ff4894b062950e46ebed8c1c7015160f8173994414a96dd286f65f0f49',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by kind
+
+You can filter events by their kind:
+
+```ruby
+filter = Nostr::Filter.new(
+  kinds: [
+    # matches events whose kind is TEXT_NOTE
+    Nostr::EventKind::TEXT_NOTE,
+    # and matches events whose kind is CONTACT_LIST
+    Nostr::EventKind::CONTACT_LIST,
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by referenced event
+
+You can filter events by the events they reference (in their `e` tag):
+
+```ruby
+filter = Nostr::Filter.new(
+  e: [
+    # matches events that reference other events whose ids match these exact IDs
+    'f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52',
+    'f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by referenced pubkey
+
+You can filter events by the pubkeys they reference (in their `p` tag):
+
+```ruby
+filter = Nostr::Filter.new(
+  p: [
+    # matches events that reference other pubkeys that match these exact IDs
+    'b698043170d580f8ae5bad4ac80b1fdb508e957f0bbffe97f2a8915fa8b34070',
+    '51f853ff4894b062950e46ebed8c1c7015160f8173994414a96dd286f65f0f49',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by timestamp
+
+You can filter events by their timestamp:
+
+```ruby
+filter = Nostr::Filter.new(
+  since: 1230981305, # matches events that are newer than this timestamp
+  until: 1292190341, # matches events that are older than this timestamp
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Limiting the number of events
+
+You can limit the number of events received:
+
+```ruby
+filter = Nostr::Filter.new(
+  limit: 420, # matches at most 420 events
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Combining filters
+
+You can combine filters. For example, to match `5` text note events that are newer than `1230981305` from the author
+`ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577`:
+
+```ruby
+filter = Nostr::Filter.new(
+  authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
+  kinds: [Nostr::EventKind::TEXT_NOTE],
+  since: 1230981305,
+  limit: 5,
+)
+subscription = client.subscribe(filter: filter)
+```

data/docs/subscriptions/updating-a-subscription.md

@@ -0,0 +1,4 @@
+# Updating a subscription
+
+Updating a subscription is done by creating a new subscription with the same id as the previous one. See
+[creating a subscription](./creating-a-subscription.md) for more information.