Add high-level documentation

https://nostr-ruby.com
2023-11-13 17:42:07 +07:00
parent b206f6504e
commit d49fac49b6
23 changed files with 1014 additions and 256 deletions
--- a/docs/core/client.md
+++ b/docs/core/client.md
@@ -0,0 +1,108 @@
+# Client
+
+Clients establish a WebSocket connection to [relays](../relays/connecting-to-a-relay). Through this connection, clients
+communicate and subscribe to a range of [Nostr events](../events) based on specified subscription filters. These filters
+define the Nostr events a client wishes to receive updates about.
+
+::: info
+Clients do not need to sign up or create an account to use Nostr. Upon connecting to a relay, a client provides
+its subscription filters. The relay then streams events that match these filters to the client for the duration of the
+connection.
+:::
+
+## WebSocket events
+
+Communication between clients and relays happen via WebSockets. The client will emit WebSocket events when the
+connection is __opened__, __closed__, when a __message__ is received or when there's an __error__.
+
+::: info
+WebSocket events are not [Nostr events](https://nostr.com/the-protocol/events). They are events emitted by the
+WebSocket connection. The WebSocket `:message` event, however, contains a Nostr event in its payload.
+:::
+
+### connect
+
+The `:connect` event is fired when a connection with a WebSocket is opened. You must call `Nostr::Client#connect` first.
+
+```ruby
+client = Nostr::Client.new
+relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
+
+client.on :connect do
+  # When this block executes, you're connected to the relay
+end
+
+# Connect to a relay asynchronously
+client.connect(relay)
+```
+
+Once the connection is open, you can send events to the relay, manage subscriptions, etc.
+
+::: tip
+Define the connection event handler before calling
+[`Nostr::Client#connect`](https://www.rubydoc.info/gems/nostr/Nostr/Client#connect-instance_method). Otherwise,
+you may miss the event.
+:::
+
+### error
+
+The `:error` event is fired when a connection with a WebSocket has been closed because of an error.
+
+```ruby
+client.on :error do |error_message|
+  puts error_message
+end
+
+# > Network error: wss://rsslay.fiatjaf.com: Unable to verify the
+# server certificate for 'rsslay.fiatjaf.com'
+```
+
+### message
+
+The `:message` event is fired when data is received through a WebSocket.
+
+```ruby
+client.on :message do |message|
+  puts message
+end
+```
+
+The message will be one of these 4 types, which must also be JSON arrays, according to the following patterns:
+- `["EVENT", <subscription_id>, <event JSON>]`
+- `["OK", <event_id>, <true|false>, <message>]`
+- `["EOSE", <subscription_id>]`
+- `["NOTICE", <message>]`
+
+::: details Click me to see how a WebSocket message looks like
+```ruby
+[
+  "EVENT",
+  "d34107357089bfc9882146d3bfab0386",
+  {
+    "content": "",
+    "created_at": 1676456512,
+    "id": "18f63550da74454c5df7caa2a349edc5b2a6175ea4c5367fa4b4212781e5b310",
+    "kind": 3,
+    "pubkey": "117a121fa41dc2caa0b3d6c5b9f42f90d114f1301d39f9ee96b646ebfee75e36",
+    "sig": "d171420bd62cf981e8f86f2dd8f8f86737ea2bbe2d98da88db092991d125535860d982139a3c4be39886188613a9912ef380be017686a0a8b74231dc6e0b03cb",
+    "tags":[
+      ["p", "1cc821cc2d47191b15fcfc0f73afed39a86ac6fb34fbfa7993ee3e0f0186ef7c"]
+    ]
+  }
+]
+```
+:::
+
+### close
+
+The `:close` event is fired when a connection with a WebSocket is closed.
+
+```ruby
+client.on :close do |code, reason|
+  puts "Error: #{code} - #{reason}"
+end
+```
+
+::: tip
+This handler is useful to attempt to reconnect to the relay.
+:::
--- a/docs/core/keys.md
+++ b/docs/core/keys.md
@@ -0,0 +1,83 @@
+# Keys
+
+To [sign events](#signing-an-event), you need a **private key**. To verify signatures, you need a **public key**. The combination of a
+private and a public key is called a **keypair**.
+
+There are a few ways to generate a keypair.
+
+## a) Generating a keypair
+
+If you don't have any keys, you can generate a keypair using the [`Nostr::Keygen`](https://www.rubydoc.info/gems/nostr/Nostr/Keygen) class:
+
+```ruby
+keygen  = Nostr::Keygen.new
+keypair = keygen.generate_key_pair
+
+keypair.private_key # => '893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900'
+keypair.public_key # => '2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558'
+```
+
+## b) Generating a private key and a public key
+
+Alternatively, if you have already generated a private key, you can extract the corresponding public key by calling
+`Keygen#extract_public_key`:
+
+```ruby
+keygen  = Nostr::Keygen.new
+
+private_key = keygen.generate_private_key
+public_key  = keygen.extract_public_key(private_key)
+
+private_key # => '893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900'
+public_key # => '2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558'
+```
+
+## c) Using existing keys
+
+If you already have a private key and a public key, you can create a keypair using the `Nostr::KeyPair` class:
+
+```ruby
+keypair = Nostr::KeyPair.new(
+  private_key: '893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900',
+  public_key: '2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558',
+)
+```
+
+## Signing an event
+
+KeyPairs are used to sign [events](../events). To create a signed event, you need to instantiate a
+[`Nostr::User`](https://www.rubydoc.info/gems/nostr/Nostr/User) with a keypair:
+
+```ruby{9,12-15}
+# a) Use an existing keypair
+keypair = Nostr::KeyPair.new(private_key: 'your-key', public_key: 'your-key')
+
+# b) Or generate a new keypair
+keygen = Nostr::Keygen.new
+keypair = keygen.generate_key_pair
+
+# Add the keypair to a user
+user = Nostr::User.new(keypair: keypair)
+
+# Create signed events
+text_note = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+```
+
+::: details Click me to view the text_note
+
+```ruby
+# text_note.to_h
+{
+  id: '5feb10973dbcf5f210cfc1f0aa338fee62bed6a29696a67957713599b9baf0eb',
+  pubkey: 'b9b9821074d1b60b8fb4a3983632af3ef9669f55b20d515bf982cda5c439ad61', # from keypair
+  created_at: 1699847447,
+  kind: 1, # Nostr::EventKind::TEXT_NOTE,
+  tags: [],
+  content: 'Your feedback is appreciated, now pay $8',
+  sig: 'e30f2f08331f224e41a4099d16aefc780bf9f2d1191b71777e1e1789e6b51fdf7bb956f25d4ea9a152d1c66717a9d68c081ce6c89c298c3c5e794914013381ab'
+}
+```
+:::
--- a/docs/core/user.md
+++ b/docs/core/user.md
@@ -0,0 +1,43 @@
+# User
+
+The class [`Nostr::User`](https://www.rubydoc.info/gems/nostr/Nostr/User) is an abstraction to facilitate the creation
+of signed events. It is not required to use it to create events, but it is recommended.
+
+Here's an example of how to create a signed event without the class `Nostr::User`:
+
+```ruby
+event = Nostr::Event.new(
+  pubkey: keypair.public_key,
+  kind: Nostr::EventKind::TEXT_NOTE,
+  tags: [],
+  content: 'Your feedback is appreciated, now pay $8',
+)
+event.sign(keypair.private_key)
+```
+
+::: details Click me to view the event
+
+```ruby
+# event.to_h
+{
+  id: '5feb10973dbcf5f210cfc1f0aa338fee62bed6a29696a67957713599b9baf0eb',
+  pubkey: 'b9b9821074d1b60b8fb4a3983632af3ef9669f55b20d515bf982cda5c439ad61',
+  created_at: 1699847447,
+  kind: 1, # Nostr::EventKind::TEXT_NOTE,
+  tags: [],
+  content: 'Your feedback is appreciated, now pay $8',
+  sig: 'e30f2f08331f224e41a4099d16aefc780bf9f2d1191b71777e1e1789e6b51fdf7bb956f25d4ea9a152d1c66717a9d68c081ce6c89c298c3c5e794914013381ab'
+}
+```
+:::
+
+And here's how to create it with the class `Nostr::User`:
+
+```ruby
+user = Nostr::User.new(keypair: keypair)
+
+event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+```