A session represents an active connection to an urbit ship.

Represents an incoming message.

An incoming message may be one of the following:

• Poke represents a response for a previous poke
• Subscribe represents a response for a subscription requests
• Diff represents a new incoming diff for a subscription
• Quit means you have been kicked from a subscription and should likely attempt to resubscribe

In all cases the first Int value represents the Id of the message it is relevant to.

Get a Session's url.

Get a Session's ship.

Get a Session's uid.

Get a Session's lastEventId.

Connect to an urbit ship and return a Session on success. Should be followed by setupEventSource (this must be done as a separate step due to the nature of Elm ports).

You can generate a unique channelId any way you wish, however the provided genChannelId function is recommended.

Alternative to connect that does not require a code.

Note: Ensure the correct cookie is set through some other means beforehand or else this will not work. Hosting from within an urbit using the :file-server app with public set to false should work, for example.

This will set up the realtime communication channel with urbit. Because Elm does not support the EventSource API required, this must be done using ports. Elm does not allow ports to be published as part of a package, but luckily the setup for this is fairly straightforward.

First, copy/paste the following into your js file and replace any references to app with the variable name of your running Elm app:

app.ports.setupUrbitEventSource.subscribe((url) => {
  const eventSource = new EventSource(url, { withCredentials: true });

  eventSource.onmessage = function (event) {
    app.ports.onUrbitMessage.send({ message: event });
  };

  eventSource.onerror = function (event) {
    app.ports.onUrbitMessage.send({ error: event });
  };
});

Next, declare a port module and the following ports to handle the initial setup and incoming messages:

port setupUrbitEventSource : String -> Cmd msg


port onUrbitMessage : (JE.Value -> msg) -> Sub msg

Now, the newly created setupUrbitEventSource can be passed as the first argument to our setupEventSource function and used to perform the necessary setup. Similarly, the onUrbitMessage function can be passed as the first argument to messages below to set up the subscription to incoming events.

setupCommand =
    Urbit.setupEventSource setupUrbitEventSource session


messagesSubscription =
    Urbit.messages onUrbitMessage GotUrbitMessage

See the Elm guide for further information regarding ports.

Subscribe to incoming messages from urbit. See setupEventSource above for instructions on how to use this. Every message received must be acknowledged by using the related ack function, otherwise urbit will stop accepting any further messages.

Acknowledge an incoming message. Must be performed for every incoming message received.

Login to an urbit without maintaining an active connection. This will allow for stateless scry and spider requests that require authentication but not others.

Note: This is not required if you have already used connect to authenticate.

Make a scry request.

Start a thread and get the response.

Poke an app on a ship.

Subscribe to ship events on some path.

Unsubscribe from an existing subscription.

Safely deletes a channel.

Recommended way to create a unique id for a session's channel. Takes the current time and returns a random generator which can then be used to generate the full ID.

Helper for generating random urbit UIDs.

Based off of https://github.com/urbit/urbit/blob/137e4428f617c13f28ed31e520eff98d251ed3e9/pkg/interface/src/lib/util.js#L3