Skip to content

Commit

Permalink
Add high-level documentation
Browse files Browse the repository at this point in the history 
https://nostr-ruby.com
  • Loading branch information
@wilsonsilva
wilsonsilva committed Nov 13, 2023
1 parent b206f65 commit 4065ae2
Show file tree
Hide file tree
Showing 23 changed files with 1,011 additions and 253 deletions.
2 changes: 1 addition & 1 deletion .editorconfig
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@ max_line_length = 120
trim_trailing_whitespace = true

# 2 space indentation
[*.rb]
[{*.rb, *.mjs}]
indent_style = space
indent_size = 2
314 changes: 83 additions & 231 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,30 @@
[![Maintainability](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/maintainability)](https://codeclimate.com/github/wilsonsilva/nostr/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/test_coverage)](https://codeclimate.com/github/wilsonsilva/nostr/test_coverage)

Asynchronous Nostr client. Please note that the API is likely to change as the gem is still in development and
has not yet reached a stable release. Use with caution.
Asynchronous Nostr client for Rubyists.

## Table of contents

- [Installation](#installation)
- [Usage](#usage)
* [Requiring the gem](#requiring-the-gem)
* [Generating a keypair](#generating-a-keypair)
* [Generating a private key and a public key](#generating-a-private-key-and-a-public-key)
* [Connecting to a Relay](#connecting-to-a-relay)
* [WebSocket events](#websocket-events)
* [Requesting for events / creating a subscription](#requesting-for-events--creating-a-subscription)
* [Stop previous subscriptions](#stop-previous-subscriptions)
* [Publishing an event](#publishing-an-event)
* [Creating/updating your contact list](#creatingupdating-your-contact-list)
* [Sending an encrypted direct message](#sending-an-encrypted-direct-message)
- [Implemented NIPs](#implemented-nips)
- [Development](#development)
- [Key features](#-key-features)
- [Installation](#-installation)
- [Quickstart](#-quickstart)
- [Documentation](#-documentation)
- [Implemented NIPs](#-implemented-nips)
- [Development](#-development)
* [Type checking](#type-checking)
- [Contributing](#contributing)
- [License](#license)
- [Code of Conduct](#code-of-conduct)
- [Contributing](#-contributing)
- [License](#-license)
- [Code of Conduct](#-code-of-conduct)

## Installation
## 🔑 Key features

- Asynchronous
- Easy to use
- Fully documented
- Fully tested
- Fully typed

## 📦 Installation

Install the gem and add to the application's Gemfile by executing:

Expand All @@ -38,248 +37,96 @@ If bundler is not being used to manage dependencies, install the gem by executin

$ gem install nostr

## Usage
## ⚡️ Quickstart

### Requiring the gem

All examples below assume that the gem has been required.
Here is a quick example of how to use the gem. For more detailed documentation, please check the
[documentation website](https://nostr-omega.vercel.app).

```ruby
# Require the gem
require 'nostr'
```

### Generating a keypair

```ruby
keygen = Nostr::Keygen.new
keypair = keygen.generate_key_pair

keypair.private_key
keypair.public_key
```

### Generating a private key and a public key

```ruby
keygen = Nostr::Keygen.new

private_key = keygen.generate_private_key
public_key = keygen.extract_public_key(private_key)
```
# Instantiate a client
client = Nostr::Client.new

### Connecting to a Relay
# a) Use an existing keypair
keypair = Nostr::KeyPair.new(
private_key: 'add-your-private-key-here',
public_key: 'add-your-public-key-here',
)

Clients can connect to multiple Relays. In this version, a Client can only connect to a single Relay at a time.
# b) Or create a new keypair
keygen = Nostr::Keygen.new
keypair = keygen.generate_keypair

You may instantiate multiple Clients and multiple Relays.
# Create a user with the keypair
user = Nostr::User.new(keypair: keypair)

```ruby
client = Nostr::Client.new
relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
# 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)
```

### WebSocket events

All communication between clients and relays happen in WebSockets.

The `:connect` event is fired when a connection with a WebSocket is opened. You must call `Nostr::Client#connect` first.

```ruby
# Listen asynchronously for the connect event
client.on :connect do
# all the code goes here
end
```

The `:close` 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'
```

The `:message` event is fired when data is received through a WebSocket.

```ruby
client.on :message do |message|
puts message
end

# [
# "EVENT",
# "d34107357089bfc9882146d3bfab0386",
# {
# "content":"",
# "created_at":1676456512,
# "id":"18f63550da74454c5df7caa2a349edc5b2a6175ea4c5367fa4b4212781e5b310",
# "kind":3,
# "pubkey":"117a121fa41dc2caa0b3d6c5b9f42f90d114f1301d39f9ee96b646ebfee75e36",
# "sig":"d171420bd62cf981e8f86f2dd8f8f86737ea2bbe2d98da88db092991d125535860d982139a3c4be39886188613a9912ef380be017686a0a8b74231dc6e0b03cb",
# "tags":[
# ["p","1cc821cc2d47191b15fcfc0f73afed39a86ac6fb34fbfa7993ee3e0f0186ef7c"]
# ]
# }
# ]
```

The `:close` event is fired when a connection with a WebSocket is closed.

```ruby
client.on :close do |code, reason|
# you may attempt to reconnect
# Send the event to the Relay
client.publish(text_note_event)

client.connect(relay)
end
```

### Requesting for events / 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` instance with as many attributes as you wish:

```ruby
client.on :connect do
# 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(
ids: ['8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8'],
authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
kinds: [Nostr::EventKind::TEXT_NOTE],
e: ["f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52"],
p: ["f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8"],
since: 1230981305,
until: 1292190341,
limit: 420,
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,
)

subscription = client.subscribe('a_random_subscription_id', filter)
end
```
# Subscribe to events matching conditions of a filter
subscription = client.subscribe(filter)

With just a few:

```ruby
client.on :connect do
filter = Nostr::Filter.new(kinds: [Nostr::EventKind::TEXT_NOTE])
subscription = client.subscribe('a_random_subscription_id', filter)
# Unsubscribe from events matching the filter above
client.unsubscribe(subscription.id)
end
```

Or omit the filter:

```ruby
client.on :connect do
subscription = client.subscribe('a_random_subscription_id')
# Listen for incoming messages and print them
client.on :message do |message|
puts message
end
```

Or even omit the subscription id:

```ruby
client.on :connect do
subscription = client.subscribe('a_random_subscription_id')
# Listen for error messages
client.on :error do |error_message|
# Handle the error
end
```

### Stop previous subscriptions

You can stop receiving messages from a subscription by calling `#unsubscribe`:

```ruby
client.unsubscribe('your_subscription_id')
```

### Publishing an event

To publish an event you need a keypair.

```ruby
# Create a keypair
keypair = Nostr::KeyPair.new(
private_key: '893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900',
public_key: '2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558',
)

# Add the keypair to the user facade
user = Nostr::User.new(keypair: keypair)

# Create a signed event
event = user.create_event(
created_at: 1667422587, # optional, defaults to the current time
kind: Nostr::EventKind::TEXT_NOTE,
tags: [], # optional, defaults to []
content: 'Your feedback is appreciated, now pay $8'
)

# Send it to the Relay
client.publish(event)
```

### Creating/updating your contact list

Every new contact list that gets published overwrites the past ones, so it should contain all entries.

```ruby
# Creating a contact list event with 2 contacts
update_contacts_event = user.create_event(
kind: Nostr::EventKind::CONTACT_LIST,
tags: [
[
"p", # mandatory
"32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245", # public key of the user to add to the contacts
"wss://alicerelay.com/", # can be an empty string or can be omitted
"alice" # can be an empty string or can be omitted
],
[
"p", # mandatory
"3efdaebb1d8923ebd99c9e7ace3b4194ab45512e2be79c1b7d68d9243e0d2681", # public key of the user to add to the contacts
"wss://bobrelay.com/nostr", # can be an empty string or can be omitted
"bob" # can be an empty string or can be omitted
],
],
)

# Send it to the Relay
client.publish(update_contacts_event)
# Listen for the close event
client.on :close do |code, reason|
# You may attempt to reconnect to the relay here
end
```

### Sending an encrypted direct message
## 📚 Documentation

```ruby
sender_private_key = '3185a47e3802f956ca5a2b4ea606c1d51c7610f239617e8f0f218d55bdf2b757'
I made a detailed documentation for this gem and it's usage. The code is also fully documented using YARD.

encrypted_direct_message = Nostr::Events::EncryptedDirectMessage.new(
sender_private_key: sender_private_key,
recipient_public_key: '6c31422248998e300a1a457167565da7d15d0da96651296ee2791c29c11b6aa0',
plain_text: 'Your feedback is appreciated, now pay $8',
previous_direct_message: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460' # optional
)

encrypted_direct_message.sign(sender_private_key)

# #<Nostr::Events::EncryptedDirectMessage:0x0000000104c9fa68
# @content="mjIFNo1sSP3KROE6QqhWnPSGAZRCuK7Np9X+88HSVSwwtFyiZ35msmEVoFgRpKx4?iv=YckChfS2oWCGpMt1uQ4GbQ==",
# @created_at=1676456512,
# @id="daac98826d5eb29f7c013b6160986c4baf4fe6d4b995df67c1b480fab1839a9b",
# @kind=4,
# @pubkey="8a9d69c56e3c691bec8f9565e4dcbe38ae1d88fffeec3ce66b9f47558a3aa8ca",
# @sig="028bb5f5bab0396e2065000c84a4bcce99e68b1a79bb1b91a84311546f49c5b67570b48d4a328a1827e7a8419d74451347d4f55011a196e71edab31aa3d6bdac",
# @tags=[["p", "6c31422248998e300a1a457167565da7d15d0da96651296ee2791c29c11b6aa0"], ["e", "ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460"]]>
- [Guide documentation](https://nostr-omega.vercel.app)
- [YARD documentation](https://rubydoc.info/gems/nostr)

# Send it to the Relay
client.publish(encrypted_direct_message)
````

## Implemented NIPs
## ✅ Implemented NIPs

- [x] [NIP-01 - Client](https://github.com/nostr-protocol/nips/blob/master/01.md)
- [x] [NIP-02 - Client](https://github.com/nostr-protocol/nips/blob/master/02.md)
- [x] [NIP-04 - Client](https://github.com/nostr-protocol/nips/blob/master/04.md)

## Development
## 🔨 Development

After checking out the repo, run `bin/setup` to install dependencies.

Expand Down Expand Up @@ -323,17 +170,22 @@ used to provide type checking and autocompletion in your editor. Run `bundle exe
an RBS definition for the given Ruby file. And validate all definitions using [Steep](https://github.com/soutaro/steep)
with the command `bundle exec steep check`.

## Contributing
## 🐞 Issues & Bugs

If you find any issues or bugs, please report them [here](https://github.com/wilsonsilva/nostr/issues), I will be happy
to have a look at them and fix them as soon as possible.

## 🤝 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/nostr.
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere
to the [code of conduct](https://github.com/wilsonsilva/nostr/blob/main/CODE_OF_CONDUCT.md).

## License
## 📜 License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Code of Conduct
## 👔 Code of Conduct

Everyone interacting in the Nostr project's codebases, issue trackers, chat rooms and mailing lists is expected
to follow the [code of conduct](https://github.com/wilsonsilva/nostr/blob/main/CODE_OF_CONDUCT.md).
Loading

0 comments on commit 4065ae2

Please sign in to comment.