mirror of
https://github.com/bsima/haskell-urbit-api.git
synced 2024-08-17 14:00:31 +03:00
85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# Haskell Urbit API
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://hackage.haskell.org/package/urbit-api)
|
|
[](https://builds.sr.ht/~ben/urbit-api?)
|
|
[](https://github.com/urbit/awesome-urbit)
|
|
|
|
|
|
|
|
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
|
|
`poke`s) 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 `wire`s.
|
|
|
|
`urbit-api` handles most of the path, session, and HTTP request stuff
|
|
automatically. See the
|
|
[haddocks](https://hackage.haskell.org/package/urbit-api/docs/Urbit-API.html)
|
|
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
|
|
|
|
```haskell
|
|
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
|
|
- graph store interface
|
|
- additional agent interfaces
|