urbit-api: Talk to Urbit from Haskell

[ bsd3, library, web ] [ Propose Tags ]

urbit-api is a Haskell library that helps you connect to the Urbit API.

Built on req, conduit, and aeson for stability and simplicity.


[Skip to Readme]
Versions [RSS] [faq] 0.2.0.0
Dependencies aeson, base (>=4.7 && <5), bytestring, conduit, conduit-extra, http-client, modern-uri, req, req-conduit, text, uuid [details]
License BSD-3-Clause
Copyright 2020 Ben Sima
Author Ben Sima
Maintainer bsima@me.com
Category Web
Home page https://github.com/bsima/haskell-urbit-api
Uploaded by bsima at 2020-11-29T15:06:41Z
Distributions NixOS:0.2.0.0
Downloads 68 total (8 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2020-11-29 [all 1 reports]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Candidates


Readme for urbit-api-0.2.0.0

[back to package description]

Haskell Urbit API

License MIT Hackage builds.sr.ht status

This library helps you talk to your Urbit from Haskell, via HTTP.

The Urbit API is a command-query API that lets you hook into apps running on your Urbit. You can submit commands (called "pokes") and subscribe to responses.

See the test.hs file for some example usages.

Design

The Urbit vane eyre is responsible for defining the API interface. The path to the API is /~/channel/..., where we send messages to the global log (called pokes) which are then dispatched to the appropriate apps. To receive responses, we stream messages from a path associated with the app, such as /mailbox/~/~zod/mc. Internally, I believe Urbit calls these wires.

urbit-api handles most of the path, session, and HTTP request stuff automatically. See the haddocks for more details.

This library is built on req, conduit, and aeson, all of which are very stable and usable libraries for working with HTTP requests and web data.

Example usage

import qualified Data.Aeson as Aeson
import Data.Aeson ((.=))
import qualified Data.Text as Text
import qualified Data.UUID.V4 as UUID

import Urbit.API

main :: IO ()
main = do
  let fakezod = Ship
    { uid = "0123456789abcdef",
      name = "zod",
      lastEventId = 1,
      url = "http://localhost:8081",
      code = "lidlut-tabwed-pillex-ridrup"
    }

  -- Establish connection
  sess <- connect ship

  -- Send a message by poking the chat-hook
  uuid <- UUID.nextRandom
  poke sess ship "zod" "chat-hook" "json" $
    Aeson.object
      [ "message"
          .= Aeson.object
            [ "path" .= Text.pack "/~/~zod/mc",
              "envelope"
                .= Aeson.object
                  [ "uid" .= UUID.toText uuid,
                    "number" .= (1 :: Int),
                    "author" .= Text.pack "~zod",
                    "when" .= (1602118786225 :: Int),
                    "letter" .= Aeson.object ["text" .= Text.pack "hello world from haskell!"]
                  ]
            ]
      ]

TODO

  • fix test suite on travis (OOM when trying to compile urbit)
  • more sophisticated test cases, also use cabal test instead of homegrown thing
  • add an exe that wraps the library with a cli
  • port to ghcjs
  • put some examples in the docs