urbit-api-0.2.0.0: Talk to Urbit from Haskell
Copyright© 2020–present Ben Sima
LicenseMIT
MaintainerBen Sima <ben@bsima.me>
Stabilityexperimental
Portabilitynon-portableo
Safe HaskellNone
LanguageHaskell2010

Urbit.API

Description

About the Urbit API

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

The Urbit vane eyre is responsible for defining the API interface. The HTTP 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.

About this library

This library helps you talk to your Urbit from Haskell, via HTTP. It handles most of the path, session, and HTTP request stuff automatically. You'll need to know what app and mark (data type) to send to, which path/wire listen to, and the shape of the message. The latter can be found in the Hoon source code, called the vase on the poke arm.

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. Released under the MIT License, same as Urbit.

Synopsis

Types

data Ship Source #

Some information about your ship needed to establish connection.

Constructors

Ship 

Fields

Instances

Instances details
Show Ship Source # 
Instance details

Defined in Urbit.API

Methods

showsPrec :: Int -> Ship -> ShowS #

show :: Ship -> String #

showList :: [Ship] -> ShowS #

type Session = CookieJar Source #

A wrapper type for the session cookies.

Functions

connect :: Ship -> IO Session Source #

Connect and login to the ship.

poke Source #

Arguments

:: ToJSON a 
=> Session

Session cookie from connect

-> Ship

Your ship

-> Text

Name of the ship to poke

-> Text

Name of the gall application you want to poke

-> Text

The mark of the message you are sending

-> a

The actual JSON message, serialized via aeson

-> IO BsResponse 

Poke a ship.

ack Source #

Arguments

:: Session

Session cookie from connect

-> Ship

Your ship

-> Int

The event number

-> IO BsResponse 

Acknowledge receipt of a message. (This clears it from the ship's queue.)

subscribe Source #

Arguments

:: Session

Session cookie from connect

-> Ship

Your ship

-> Text

The path to subscribe to.

-> ConduitM ByteString Void (ResourceT IO) a

A handler conduit to receive the response from the server, e.g. Data.Conduit.Binary.sinkFile "my-file.out"

-> IO a 

Subscribe to ship events on some path.

Orphan instances