Add high-level documentation

https://nostr-ruby.com

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
+```

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)
+```

docs/subscriptions/filtering-subscription-events.md

@@ -0,0 +1,131 @@
+# Filtering events
+
+## Filtering by id
+
+You can filter events by their ids or prefixes:
+
+```ruby
+filter = Nostr::Filter.new(
+  ids: [
+    # matches events with these exact IDs
+    '8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8',
+    '461544014d87c9eaf3e76e021240007dff2c7afb356319f99c741b45749bf82f',
+    # and match events whose id start with '76fbe'
+    '76fbe',
+    # and match events whose id start with 'b'
+    'b',
+  ]
+)
+subscription = client.subscribe(filter: filter)
+```
+
+## Filtering by author
+
+You can filter events by their author's pubkey or prefix:
+
+```ruby
+filter = Nostr::Filter.new(
+  authors: [
+    # matches events whose (authors) pubkey match these exact IDs
+    'b698043170d580f8ae5bad4ac80b1fdb508e957f0bbffe97f2a8915fa8b34070',
+    '51f853ff4894b062950e46ebed8c1c7015160f8173994414a96dd286f65f0f49',
+    # and match events whose (authors) pubkey start with 'db508e957'
+    'db508e957',
+    # and match events whose (authors) pubkey start with 'f'
+    'f',
+  ]
+)
+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',
+    # and match events that reference other events whose id starts with '76fbe'
+    '76fbe',
+    # and match events that reference other events whose id starts with 'b'
+    'b',
+  ]
+)
+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',
+    # and match events that reference other pubkeys that start with 'db508e957'
+    'db508e957',
+    # and match events that reference other pubkeys that start with 'f'
+    'f',
+  ]
+)
+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)
+```

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.