urbit-api 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 626e3718491acdc2cd451fc847e489bac5bb4eb1490797bf6417fb9352c8b17b
-  data.tar.gz: a744f2e30e52b901d1e681bdb8a2109f48facd9bcdc45cfc9148a11a0f32d059
+  metadata.gz: 2cef1b4e2c8a8a7ef8ba203f66e92e516e563c7b32119e98ee55366983e72dd3
+  data.tar.gz: dc6267d7c21e034c6725309a15678b09b4e0d8713990b5e975c94ef25475caed
 SHA512:
-  metadata.gz: 31738b651665457fb50113b26e6f3fe319473bc8112c01ba9fedc58f27c474a62a40a1619ee0c1c765dbf70582f61c54885521a3b53c91bcd30b963ff6ca0d5b
-  data.tar.gz: 36f2bcab1490c8dfe2b83cd875dba0d9571f53f65e7760d0cdfd38ccd8b5eb21753cf039cda46d11cff9f493d9cf4d818397ec36a8b66ea334e79459f8cf3d1c
+  metadata.gz: 9b19087253b1b6864e0941b94513f530aee01856357d590468e670273412a273a8ad4e514bc21c21ea86bc24877e4cc72b9ce475cbf218c2f53efafd462e2cb7
+  data.tar.gz: 1443c08a0370fd78bf33dca3c701aba09669421d434b10a475544a0828fe1eaae3ac1a222aa963654e29e800b3f7ab019efd73bbd2d9dbb6b00f4c775f52e63c

data/.ruby-version

@@ -1 +1,2 @@
-2.7.2
+2.7.4
+

data/README.md

@@ -1,8 +1,13 @@
 # Urbit::Api
+
 ## The Ruby interface to the Urbit HTTP API
 
 This library wraps the Urbit ship http interface exposing it as a Ruby gem.
 
+[![awesome urbit badge](https://img.shields.io/badge/~-awesome%20urbit-lightgrey)](https://github.com/urbit/awesome-urbit)
+[![Gem Version](https://badge.fury.io/rb/urbit-api.svg)](https://badge.fury.io/rb/urbit-api)
+[![License](https://img.shields.io/github/license/Zaxonomy/urbit-ruby)](https://github.com/Zaxonomy/urbit-ruby/blob/master/LICENSE.txt)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -21,39 +26,194 @@ Or install it yourself as:
 
 ## Usage
 
-```rb
-# TODO: fix namespacing :)
-require 'urbit/urbit'
+```sh
+> bin/console
 
 # This will instantiate a ship that connects to the fake `~zod` dev server by default
 # See Urbit docs for more info: https://urbit.org/using/develop/
-ship = Urbit.new
-# => #<Urbit::Ship:0x00007fa74b87f920 ...
-
-ship.logged_in?
-# => false
-
-ship.login
-# => #<Urbit::Ship:0x00007fa74b87f920 ...
-
-ship.logged_in?
-# => true
+[1] pry(main)> ship = Urbit.new
+=> #<Urbit::Ship:0x00007fa74b87f920 ...
+
+OR... with config file...
+> ship = Urbit.connect(config_file: '_config-barsyr-latreb.yml')
+
+> ship.logged_in?
+=> false
+
+> ship.login
+=> #<Urbit::Ship:0x00007fa74b87f920 ...
+
+> ship.logged_in?
+=> true
+
+> ship.to_s
+=> "a Ship(name: '~barsyr-latreb', host: 'http://localhost', port: '8080')"
+
+> channel = ship.subscribe(app: 'graph-store', path: '/updates')
+=> a Channel (Open) on ~barsyr-latreb(name: 'Channel-0', key: '1622836437b540b4')
+
+# Subscribing works by opening a Channel. Your ships has a collection of all it's open Channels.
+> channel = ship.open_channels.first
+=> a Channel (Open) on ~barsyr-latreb(name: 'Channel-0', key: '1622836437b540b4')
+
+# Notice that it's the same one.
+
+# Every Channel has a unique key to identify it.
+> channel.key
+=> "16142890875c348d"
+
+# The Channel has a Receiver that will now be listening on the app and path you specified. Each time an event is sent in it will be stored in the receiver's facts collection.
+> channel.receiver.facts.count
+=> 12
+
+# Perform any action through landscape that would initiate an update into %graph-store...
+# In this case I have added a comment to a local notebook.
+> channel.receiver.facts.last
+=> a Fact({:ship=>{:name=>"~barsyr-latreb", :host=>"http://localhost", :port=>"8080"}, :resource=>"~barsyr-latreb/test0-996", :acknowleged=>true, :is_graph_update=>true})
+
+#  Your ship keeps a collection of all the messages sent to urbit:
+> channel.sent_messages.collect {|m| m.to_s}
+=> [
+    "a Message({:action=>"poke", :app=>"hood", :id=>1, :json=>"Opening Airlock", :mark=>"helm-hi", :ship=>"barsyr-latreb"})",
+    "a Message({:action=>"subscribe", :app=>"graph-store", :id=>2, :path=>"/updates", :ship=>"barsyr-latreb"})",
+    "a Message({"id"=>3, "action"=>"ack", "event-id"=>"0"})",
+    "a Message({"id"=>4, "action"=>"ack", "event-id"=>"1"})",
+    "a Message({"id"=>5, "action"=>"ack", "event-id"=>"2"})"
+   ]
+
+#
+# --------------------------------------------------------------------
+# Poke
+# --------------------------------------------------------------------
+#
+> ship.poke(app: 'hood', mark: 'helm-hi', message: 'Opening Airlock')
+=> a Channel (Open) on ~barsyr-latreb(name: 'Channel-0', key: '1630355920a717e1')
+
+#
+# --------------------------------------------------------------------
+# Scry
+# --------------------------------------------------------------------
+#
+# Retrieving your ship's base hash using scry....
+> ship.scry(app: 'file-server', path: '/clay/base/hash')
+# => {:status=>200, :code=>"ok", :body=>"\"e75k5\""}
+
+#
+# --------------------------------------------------------------------
+# Spider
+# --------------------------------------------------------------------
+#
+# Creating a new Notebook in "My Channels" using %spider....
+> create_json = %Q(
+        {"create": {"resource": { "ship": "~zod", "name": "random_name"},
+        "title": "Testing",
+        "description": "Testing Un-Managed Graph Creation",
+        "associated" : {"policy": {"invite": {"pending": []}}},
+        "module": "publish", "mark": "graph-validator-publish"}}
+  )
+> ship.spider(mark_in: 'graph-view-action', mark_out: 'json', thread: 'graph-create', data: create_json)
+# => {:status=>200, :code=>"ok", :body=>"\"e75k5\""}
+
+#
+# --------------------------------------------------------------------
+# %graph-store
+# --------------------------------------------------------------------
+#
+> puts ship.graph_names
+~barsyr-latreb/dm-inbox
+~darlur/announce
+~bitbet-bolbel/urbit-community-5.963
+~winter-paches/top-shelf-6391
+~winter-paches/the-great-north-7.579
+~barsyr-latreb/test0-996
+~fabled-faster/test-chat-a-5919
+~barsyr-latreb/test1-4287
+~darrux-landes/welcome-to-urbit-community
+~millyt-dorsen/finance-2.962
+~fabled-faster/interface-testing-facility-683
+~darlur/help-desk-4556
+=>
+
+# Reference a graph by name and return a single node.
+> puts ship.graph(resource: '~winter-paches/top-shelf-6391').node(index: "170.141.184.505.207.751.870.046.689.877.378.990.080")
+a Node({:index=>"170.141.184.505.207.751.870.046.689.877.378.990.080", :author=>"witfyl-ravped", :contents=>[{"text"=>"the patches don't really bother me though tbh"}], :time_sent=>1629316468195, :is_parent=>false, :child_count=>0})
+=>
+
+# You can also reference a graph by its index in the graphs collection.
+> puts ship.graphs[3].node(index: "170.141.184.505.207.751.870.046.689.877.378.990.080")
+a Node({:index=>"170.141.184.505.207.751.870.046.689.877.378.990.080", :author=>"witfyl-ravped", :contents=>[{"text"=>"the patches don't really bother me though tbh"}], :time_sent=>1629316468195, :is_parent=>false, :child_count=>0})
+=>
+
+# Return the contents of the 5 oldest nodes of a graph
+> graph = ship.graph(resource: '~winter-paches/top-shelf-6391')
+> graph.oldest_nodes(count: 5).sort.each {|n| p n.contents};nil
+[{"text"=>"watching the 2020 stanley cup finals (tampa (sigh) just went up 2-0 in game 3) and i thought: \"the great north has to have a hockey chat, eh?\""}]
+[{"text"=>"we'll see if this has legs. ;)"}]
+[{"text"=>"shortie! now 2-1 tampa."}]
+[{"text"=>"looks like tampa's going to go up 2-1. as a canadian this geographically depresses me. :/"}]
+[{"text"=>"anyone in the stands?"}]
+=>
+
+# A single Node. In this case, the 3rd oldest node in the graph.
+> puts graph.nodes[2].contents
+{"text"=>"shortie! now 2-1 tampa."}
+=>
+
+# Getting the next newer Node. Remember that it always returns an Array, hence the '#first'.
+> puts graph.nodes[2].next.first.contents
+{"text"=>"looks like tampa's going to go up 2-1. as a canadian this geographically depresses me. :/"}
+=>
+
+# Return the indexes of the newest 5 nodes of a graph
+> ship.graph(resource: '~winter-paches/top-shelf-6391').newest_nodes(count: 5).sort.each {|n| p n.index};nil
+"170.141.184.505.209.257.330.601.508.862.548.770.816"
+"170.141.184.505.209.375.247.350.471.711.992.578.048"
+"170.141.184.505.209.545.972.004.310.065.795.301.376"
+"170.141.184.505.209.627.337.970.761.265.544.429.568"
+"170.141.184.505.209.644.102.846.398.558.514.446.336"
+=>
+
+# Fetching nodes older relative to another node. (See indexes above)
+> puts (node = ship.graph(resource: '~winter-paches/top-shelf-6391').node(index: "170.141.184.505.209.644.102.846.398.558.514.446.336"))
+a Node({:index=>"170.141.184.505.209.644.102.846.398.558.514.446.336", :author=>"winter-paches", :contents=>[{"text"=>"yep. that's how i did it as a kid. harry caray was the white sox announcer before he turned traitor and went to the cubs."}], :time_sent=>1629419046028, :is_parent=>false, :child_count=>0})
+=>
+
+> puts node.previous
+a Node({:index=>"170.141.184.505.209.627.337.970.761.265.544.429.568", :author=>"pathus-hiddyn", :contents=>[{"text"=>"Lol oh man I haven’t listened to a baseball game on the radio in forever. It is great isn’t it. "}], :time_sent=>1629418137668, :is_parent=>false, :child_count=>0})
+=>
+
+> node.previous(count: 4).each {|n| p n.index};nil
+"170.141.184.505.209.257.330.601.508.862.548.770.816"
+"170.141.184.505.209.375.247.350.471.711.992.578.048"
+"170.141.184.505.209.545.972.004.310.065.795.301.376"
+"170.141.184.505.209.627.337.970.761.265.544.429.568"
+
+#
+# --------------------------------------------------------------------
+# %settings-store
+# --------------------------------------------------------------------
+#
+> ship.setting(desk: 'landscape', bucket: 'calm').each {|e| p e};nil
+["hideUtilities", false]
+["hideGroups", false]
+["hideAvatars", true]
+["hideUnreads", true]
+["hideNicknames", true]
+
+> ship.subscribe(app: 'settings-store', path: '/all')
+=> a Channel (Open) on ~barsyr-latreb(name: 'Channel-0', key: '164375139513eacb')
+
+# We are now listening for changes in any settings on the ship. Go to Landscape and toggle the "Hide Groups" button...
+Received a Fact for [a Channel (Open) on ~barsyr-latreb(name: 'Channel-0', key: '164375139513eacb')] -- [message] -- [{"json":{"settings-event":{"put-entry":{"bucket-key":"calm","desk":"landscape","entry-key":"hideGroups","value":true}}},"id":1,"response":"diff"}]
+
+> ship.setting(desk: 'landscape', bucket: 'calm').each {|e| p e};nil
+["hideUtilities", false]
+**["hideGroups", true]**
+["hideAvatars", true]
+["hideUnreads", true]
+["hideNicknames", true]
 
-channel = ship.open_channel('my-channel')
-# => #<Urbit::Channel:0x00007fa74b291e50 ...
-
-channel.key
-# => "16142890875c348d"
-
-ship.channels.first.key
-# => "16142890875c348d"
-
-receiver = channel.subscribe(app: 'graph-store', path: '/updates')
-# => #<Urbit::Receiver:0x00007fd3928eba58
-
-# This receiver will now be listening on the app and path you specified. Each time an event is sent in it will be stored in the receiver's events collection.
 ```
-
 ### Configuration
 
 Configure your ship using a config file or constructor keyword arguments. Either or both can be used; the keyword args will override any values set via config file.
@@ -83,11 +243,10 @@ ship = Urbit.new(host: '127.0.0.1', port: '8080')
 ```sh
 bin/test
 ```
-### ~zod
-
 Tests assume that an instance of a ["fake" development Urbit ship](https://urbit.org/using/develop/) (one not connected to the live network) will be running, available at `http://localhost:8080`.
+### "fake" ~zod
 
-To create a development ship:
+To create this development ship:
 ```sh
 ./urbit -F zod
 ```
@@ -95,7 +254,7 @@ To create a development ship:
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 

data/bin/console

@@ -4,8 +4,11 @@ require "bundler/setup"
 require "pry"
 require "urbit/urbit"
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
+puts "Welcome! This is an interactive environment to explore your Urbit ship."
+puts "You create a config file with connection details for your ship and off you go."
+puts ""
 puts "e.g., ship = Urbit.new(config_file: 'my_config.yml')"
+puts "=> a Ship(name: '~barsyr-latreb', host: 'http://localhost', port: '8080')"
+
+Pry.config.print = proc { |output, value| output.puts "=> #{value}" }
 Pry.start

data/lib/urbit/ack_message.rb

@@ -1,18 +1,23 @@
-require 'json'
-
-require 'urbit/message'
-
 module Urbit
   class AckMessage < Message
-    def initialize(channel, sse_message_id)
-      @action  = 'ack'
-      @channel = channel
-      @id      = 0
+    attr_reader :ack_id
+
+    def initialize(channel:, sse_message_id:)
+      super(channel: channel)
       @ack_id  = sse_message_id
     end
 
+    def action
+      "ack"
+    end
+
     def to_h
-      {'id' => id, 'action' => action, 'event-id' => @ack_id}
+      # Need to use the older hash style due to the key having a dash.
+      {'id' => self.id, 'action' => self.action, 'event-id' => self.ack_id}
+    end
+
+    def to_s
+      "an AckMessage(#{self.to_h})"
     end
   end
 end

data/lib/urbit/api/version.rb

@@ -1,5 +1,5 @@
 module Urbit
   module Api
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/urbit/channel.rb

@@ -1,52 +1,58 @@
-require 'faraday'
 require 'securerandom'
 
 require 'urbit/message'
 require 'urbit/receiver'
+require 'urbit/close_message'
+require 'urbit/poke_message'
 require 'urbit/subscribe_message'
 
 module Urbit
   class Channel
     attr_accessor :messages
-    attr_reader :key, :name, :ship
+    attr_reader :key, :name, :receiver, :ship
 
-    def initialize(ship, name)
+    def initialize(ship:, name:)
       @ship          = ship
       @key           = "#{Time.now.to_i}#{SecureRandom.hex(3)}"
       @messages      = []
       @name          = name
+      @receiver      = nil
       @is_open       = false
-      @is_subscribed = false
     end
 
     def close
       # puts "closing #{name}"
-      m = Urbit::CloseMessage.new(self)
-      @is_open = !self.send_message(m)
+      m = Urbit::CloseMessage.new(channel: self)
+      @is_open = !self.send(message: m)
     end
 
     def closed?
       !@is_open
     end
 
-    def open(a_message_string)
-      m = Urbit::Message.new(self, "poke", "hood", "helm-hi", a_message_string)
-      @is_open = self.send_message(m)
-    end
-
     def open?
       @is_open
     end
 
-    def queue_message(a_message)
-      a_message.id = self.sent_messages.size + 1
-      @messages << a_message
+    #
+    # One way to open a channel by "poking" an urbit app with a mark and a (json) message.
+    # A typical example of this is poking the 'hood' app using the mark 'helm-hi' to start a DM chat.
+    #
+    def poke(app:, mark:, message:)
+      @is_open = self.send(message: (Urbit::PokeMessage.new(channel: self, app: app, mark: mark, a_string: message)))
+      @receiver = Urbit::Receiver.new(channel: self)
+      self
+    end
+
+    def queue(message:)
+      message.id = self.sent_messages.size + 1
+      @messages << message
     end
 
     # Answers true if message was successfully sent.
-    def send_message(a_message)
-      self.queue_message(a_message)
-      resp = a_message.transmit
+    def send(message:)
+      self.queue(message: message)
+      resp = message.transmit
       resp.reason_phrase == "ok"
     end
 
@@ -58,14 +64,19 @@ module Urbit
       self.open? ? "Open" : "Closed"
     end
 
-    def subscribe(app, path)
-      m = Urbit::SubscribeMessage.new(self, app, path)
-      @is_subscribed = self.send_message(m)
-      receiver = Urbit::Receiver.new(self)
+    #
+    # Subscribe to an app at a path.
+    # Returns a Receiver which will begin to get back a stream of facts... which is a... Dictionary? Encyclopedia?
+    #
+    def subscribe(app:, path:)
+      m = Urbit::SubscribeMessage.new(channel: self, app: app, path: path)
+      @is_open = self.send(message: m)
+      @receiver = Urbit::Receiver.new(channel: self)
+      self
     end
 
     def subscribed?
-      @is_subscribed
+      @is_open
     end
 
     def to_s

data/lib/urbit/chat_channel.rb

@@ -0,0 +1,22 @@
+require 'securerandom'
+
+require 'urbit/message'
+require 'urbit/receiver'
+require 'urbit/close_message'
+require 'urbit/poke_message'
+require 'urbit/subscribe_message'
+
+module Urbit
+  class ChatChannel < Channel
+    # def messages
+    #   self.fetch_all_nodes if @nodes.empty?
+    #   @nodes
+    # end
+
+    # def newest_messages(count = 100)
+    #   self.fetch_newest_nodes(count) if @nodes.empty?
+    #   self.nodes
+    # end
+
+  end
+end

data/lib/urbit/close_message.rb

@@ -0,0 +1,15 @@
+module Urbit
+  class CloseMessage < Message
+    def initialize(channel:)
+      super(channel: channel)
+    end
+
+    def action
+      "delete"
+    end
+
+    def to_h
+      {id: self.id, action: self.action}
+    end
+  end
+end

data/lib/urbit/fact.rb

@@ -0,0 +1,206 @@
+require 'urbit/graph'
+require 'urbit/node'
+require 'urbit/parser'
+
+module Urbit
+  class Fact
+    attr_reader :ack
+
+    def initialize(channel:, event:)
+      @channel = channel
+      @data = event.data
+      @type = event.type
+      puts "Received a Fact for [#{channel}] -- [#{@type}] -- [#{@data}]"
+    end
+
+    #
+    # This is a Facotry method to make the proper Fact subclass from
+    # a Channel Event.
+    #
+    def self.collect(channel:, event:)
+      contents = JSON.parse(event.data)
+      return Fact.new(channel: channel, event: event)              if contents["json"].nil?
+      return SettingsEventFact.new(channel: channel, event: event) if contents["json"]["settings-event"]
+
+      return Fact.new(channel: channel, event: event)              if contents["json"]["graph-update"].nil?
+      return AddGraphFact.new(channel: channel, event: event)      if contents["json"]["graph-update"]["add-graph"]
+      return AddNodesFact.new(channel: channel, event: event)      if contents["json"]["graph-update"]["add-nodes"]
+      return RemoveGraphFact.new(channel: channel, event: event)   if contents["json"]["graph-update"]["remove-graph"]
+
+      return Fact.new(channel: channel, event: event)
+    end
+
+    def add_ack(ack:)
+      @ack = :ack
+    end
+
+    def contents
+      JSON.parse(@data)
+    end
+
+    def for_this_ship?
+      self.ship == @channel.ship
+    end
+
+    def graph_update?
+      false
+    end
+
+    def is_acknowledged?
+      !@ack.nil?
+    end
+
+    def raw_json
+      nil
+    end
+
+    def ship
+      @channel.ship
+    end
+
+    def to_h
+      {
+        ship:            self.ship.to_h,
+        acknowleged:     self.is_acknowledged?,
+        is_graph_update: self.graph_update?
+      }
+    end
+
+    def to_s
+      "a #{self.class.name}(#{self.to_h})"
+    end
+  end
+
+  class GraphUpdateFact < Fact
+    def initialize(channel:, event:)
+      super channel: channel, event: event
+    end
+
+    #
+    # Attach this new fact as a node to its Graph.
+    #
+    def attach_parser
+      # puts "Received a graph update for [#{self.ship.graph(resource: self.resource)}]"
+      if self.incoming_graph
+        # puts "Received an add_graph event: #{self.raw_json} on #{self.resource}"
+        self.create_parser
+      end
+    end
+
+    def create_parser
+      nil
+    end
+
+    def graph_update?
+      true
+    end
+
+    def incoming_graph
+      self.ship.graph(resource: self.resource)
+    end
+
+    def resource
+      return "~#{self.resource_h["ship"]}/#{self.resource_h["name"]}" unless self.resource_h.nil?
+    end
+
+    def resource_h
+      self.raw_json["resource"]
+    end
+
+    def root_h
+      self.contents["json"]["graph-update"]
+    end
+
+    def to_h
+      super.merge!(resource: self.resource)
+    end
+  end
+
+  class AddGraphFact < GraphUpdateFact
+    def initialize(channel:, event:)
+      super channel: channel, event: event
+    end
+
+    def create_parser
+      Urbit::AddGraphParser.new(for_graph: incoming_graph,  with_json: self.raw_json).add_nodes
+    end
+
+    def raw_json
+      self.root_h["add-graph"]
+    end
+  end
+
+  class AddNodesFact < GraphUpdateFact
+    def initialize(channel:, event:)
+      super channel: channel, event: event
+    end
+
+    def create_parser
+      Urbit::AddNodesParser.new(for_graph: incoming_graph,  with_json: self.raw_json).add_nodes
+    end
+
+    def raw_json
+      self.root_h["add-nodes"]
+    end
+  end
+
+  class RemoveGraphFact < GraphUpdateFact
+    def initialize(channel:, event:)
+      super channel: channel, event: event
+    end
+
+    def create_parser
+      Urbit::RemoveGraphParser.new(for_graph: incoming_graph,  with_json: self.raw_json)
+    end
+
+    def raw_json
+      self.root_h["remove-graph"]
+    end
+
+    def resource_h
+      self.raw_json
+    end
+  end
+
+  class SettingsEventFact < Fact
+    def initialize(channel:, event:)
+      super channel: channel, event: event
+
+      if self.for_this_ship?
+        # See if we already have this setting, if no add it, if yes update it.
+        if (entries = channel.ship.setting(bucket: self.bucket))
+          entries[self.entry] = self.value
+        end
+      end
+    end
+
+    def bucket
+      self.contents["bucket-key"]
+    end
+
+    def contents
+      JSON.parse(@data)["json"]["settings-event"]["put-entry"]
+    end
+
+    def desk
+      self.contents["desk"]
+    end
+
+    def entry
+      self.contents["entry-key"]
+    end
+
+    def to_h
+      super.merge!({
+        bucket: self.bucket,
+        desk:   self.desk,
+        entry:  self.entry,
+        value:  self.value
+      })
+    end
+
+    def value
+      self.contents["value"]
+    end
+  end
+end