UrbitEx.API.Graph (UrbitEx v0.5.7) View Source

Client API to interact with graphs on Urbit. Create channels, delete them, send messages, add posts, etc. All interaction with present Graph Store based applications is here.

Link to this section Summary

Functions

Adds a link to a Collection channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a text string and a url string. Triggers one graph-update event (the link itself). Eyre returns a 200 response.

Adds a comment to a Notebook post or a Collection link. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an index string, a text string and an optional custom token list. See docs on add_post function above for notes on how custom token lists can be useful. Triggers one graph-update event (the comment itself). Eyre returns a 200 response.

Adds a post to a Notebook channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a title string, a text string, and an optional custom list of token maps. Graph Store posts tokens can be text, mention, url, code or reference. In elixir a valid content list would look like [%{text: title}, %{url: "https://urbitasia.com"}, %{mention: "~mirtyl-wacdec"}] If no custom tokens are given, the function uses the default tokenizer used by Landscape. Landscape's notebook post tokenizer renders the first text map as the title, the second as the post body. A custom tokenizer can be used to format text for custom clients without need for a custom backend. Triggers one graph-update event (the post itself). Eyre returns a 200 response.

Creates a channel in a group. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct (for the group), a title string, a name string (lower ascii, no spaces), a description string, and a channel type atom (strings work too, it's all json anyway). As in group names, Landscape enforces title and name being similar, no real need for that. Types can be :chat for Chats, :publish for Notebooks or :link for Collections. Successful creation triggers one metadata-updateevent and one graph-update event. Eyre returns a 200 response.

Creates a private channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct (for the group), a title string, a name string (lower ascii, no spaces), a description string, a channel type atom (strings work too, it's all json anyway), and a list of invitees. As in group names, Landscape enforces title and name being similar, no real need for that. Types can be :chat for Chats, :publish for Notebooks or :link for Collections. Setting invitees at resource creation works unlike with groups. Note that private "chat" channels are in effect DMs and will show up as DMs in Landscape, although they will strangely if you don't follow Landscape naming (see below). Successful creation triggers one metadata-updateevent and one graph-update event. Eyre returns a 200 response.

Deletes a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers one metadata-updateevent and one graph-update event. Unless it's a private channel then the metadata-update event is replaced by a group-update one (??). Eyre returns a 200 response.

Deletes a node in any channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct and list of index strings. Index strings must have a preceding slash, i.e. "/170141184505071972989094238161226170368" Revisable nodes (notebook posts and comments) must delete the revision container and the first child. Triggers one graph-update event. Eyre returns a 204 response.

Disables the group feed in a group. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers one metadata-update and one graph-update event. Eyre returns a 200 response.

Edits a comment in a Notebook or Link channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an UrbitEx.Node struct of the comment (the one you want to edit), a title string, a text string, and an optional custom list of token maps (see above). Triggers one graph-update event (the post itself). Eyre returns a 200 response.

Edits a post in a Notebook channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an UrbitEx.Node struct of the post you want to edit (the larger node, not the posts revision container node), a title string, a text string, and an optional custom list of token maps (see above). Triggers one graph-update event (the post itself). Eyre returns a 200 response.

Enables the group feed in a group. Takes an UrbitEx.Session struct an UrbitEx.Resource struct, and the permission setting. Can be "host-feed", "admin-feed", or "" (empty) to allow everyone to post on the feed. Triggers one metadata-update and one graph-update event. Validator for group feeds is graph-validator-post, cf: graph-validator-chat or graph-validator-publish. Eyre returns a 200 response.

Fetches a single node from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct and a node index. GET requests trigger no SSE events. Eyre returns a 200 response.

Fetches the all channels which the ship is a member of. Takes an UrbitEx.Session struct. GET requests trigger no SSE events. Eyre returns a 200 response. Function returns a list of UrbitEx.Resource structs. You can convert the graph to a list with UrbitEx.Graph.to_list/1

Fetches latest nodes from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and a message count integer. Count limits appears to be 999. You can pass it an index string optionally (passed index can have a "/" or not, doesn't matter). This is the endpoint Landscape uses to render the chat. But it works fine with Notebooks or Collections too. GET requests trigger no SSE events. Eyre returns a 200 response. Function returns a graph (not a list!) of UrbitEx.Node structs, according to count requested. You can convert the graph to a list with UrbitEx.Graph.to_list/1

Fetches nodes from a channel which are older than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an index string (passed index can have a "/" or not, doesn't matter) and a message count integer. GET requests trigger no SSE events. Eyre returns a 200 response.

Fetches oldest nodes from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and a message count integer. GET requests trigger no SSE events. Eyre returns a 200 response.

Fetches nodes from a channel which are older than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and two index strings, start and finish. GET requests trigger no SSE events. Eyre returns a 200 response.

Fetches tag queries. Takes an UrbitEx.Session struct. GET requests trigger no SSE events. Eyre returns a 200 response. Not sure what this is about.

Fetches tags. Takes an UrbitEx.Session struct. GET requests trigger no SSE events. Eyre returns a 200 response. Not sure what this is about.

Fetches the whole node graph from a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. This is the endpoint Landscape uses to render Notebooks and Collections. You can run it on a Chat but it'll timeout with big ones (over 999 nodes?). GET requests trigger no SSE events. Eyre returns a 200 response. Function returns a graph (not a list!) of UrbitEx.Node structs, according to count requested. You can convert the graph to a list with UrbitEx.Graph.to_list/1

Fetches nodes from a channel which are younger than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an index string (passed index can have a "/" or not, doesn't matter) and a message count integer. GET requests trigger no SSE events. Eyre returns a 200 response.

Joins a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers two graph-update event, one with a list of keys and for add-graph. Eyre returns a 200 response.

Leaves a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers one graph-update event. Eyre returns a 200 response.

Send message to a chat channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a message string, and an optional custom list of token maps. Graph Store posts tokens can be text, mention, url, code or reference. In elixir a valid content list would look like [%{text: title}, %{url: "https://urbitasia.com"}, %{mention: "~mirtyl-wacdec"}] If no custom tokens are given, the function uses the default tokenizer used by Landscape. A custom tokenizer can be used to format text for custom clients without need for a custom backend. Triggers one graph-update event (the message itself). Eyre returns a 200 response.

Starts a Direct Message with a ship. Takes an UrbitEx.Session struct and an Urbit ID to invite. Just syntactic sugar over create_private_channel above. Follows Landscape naming convention.

Link to this section Functions

Link to this function

add_collection_link(session, resource, text, url)

View Source

Adds a link to a Collection channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a text string and a url string. Triggers one graph-update event (the link itself). Eyre returns a 200 response.

Link to this function

add_comment(session, resource, node, text, custom \\ nil)

View Source

Adds a comment to a Notebook post or a Collection link. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an index string, a text string and an optional custom token list. See docs on add_post function above for notes on how custom token lists can be useful. Triggers one graph-update event (the comment itself). Eyre returns a 200 response.

Link to this function

add_post(session, resource, title, text, custom \\ nil)

View Source

Adds a post to a Notebook channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a title string, a text string, and an optional custom list of token maps. Graph Store posts tokens can be text, mention, url, code or reference. In elixir a valid content list would look like [%{text: title}, %{url: "https://urbitasia.com"}, %{mention: "~mirtyl-wacdec"}] If no custom tokens are given, the function uses the default tokenizer used by Landscape. Landscape's notebook post tokenizer renders the first text map as the title, the second as the post body. A custom tokenizer can be used to format text for custom clients without need for a custom backend. Triggers one graph-update event (the post itself). Eyre returns a 200 response.

Link to this function

create_group_channel(session, group, title, name, description, type)

View Source

Creates a channel in a group. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct (for the group), a title string, a name string (lower ascii, no spaces), a description string, and a channel type atom (strings work too, it's all json anyway). As in group names, Landscape enforces title and name being similar, no real need for that. Types can be :chat for Chats, :publish for Notebooks or :link for Collections. Successful creation triggers one metadata-updateevent and one graph-update event. Eyre returns a 200 response.

Link to this function

create_private_channel(session, title, name, description, type, invitees \\ [])

View Source

Creates a private channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct (for the group), a title string, a name string (lower ascii, no spaces), a description string, a channel type atom (strings work too, it's all json anyway), and a list of invitees. As in group names, Landscape enforces title and name being similar, no real need for that. Types can be :chat for Chats, :publish for Notebooks or :link for Collections. Setting invitees at resource creation works unlike with groups. Note that private "chat" channels are in effect DMs and will show up as DMs in Landscape, although they will strangely if you don't follow Landscape naming (see below). Successful creation triggers one metadata-updateevent and one graph-update event. Eyre returns a 200 response.

Link to this function

delete_channel(session, resource)

View Source

Deletes a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers one metadata-updateevent and one graph-update event. Unless it's a private channel then the metadata-update event is replaced by a group-update one (??). Eyre returns a 200 response.

Link to this function

delete_node(session, resource, indices)

View Source

Deletes a node in any channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct and list of index strings. Index strings must have a preceding slash, i.e. "/170141184505071972989094238161226170368" Revisable nodes (notebook posts and comments) must delete the revision container and the first child. Triggers one graph-update event. Eyre returns a 204 response.

Link to this function

disable_group_feed(session, group)

View Source

Disables the group feed in a group. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers one metadata-update and one graph-update event. Eyre returns a 200 response.

Link to this function

edit_comment(session, resource, node, text, custom \\ nil)

View Source

Edits a comment in a Notebook or Link channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an UrbitEx.Node struct of the comment (the one you want to edit), a title string, a text string, and an optional custom list of token maps (see above). Triggers one graph-update event (the post itself). Eyre returns a 200 response.

Link to this function

edit_post(session, resource, node, title, text, custom \\ nil)

View Source

Edits a post in a Notebook channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an UrbitEx.Node struct of the post you want to edit (the larger node, not the posts revision container node), a title string, a text string, and an optional custom list of token maps (see above). Triggers one graph-update event (the post itself). Eyre returns a 200 response.

Link to this function

enable_group_feed(session, group, permission)

View Source

Enables the group feed in a group. Takes an UrbitEx.Session struct an UrbitEx.Resource struct, and the permission setting. Can be "host-feed", "admin-feed", or "" (empty) to allow everyone to post on the feed. Triggers one metadata-update and one graph-update event. Validator for group feeds is graph-validator-post, cf: graph-validator-chat or graph-validator-publish. Eyre returns a 200 response.

Link to this function

fetch_index(session, resource, index)

View Source

Fetches a single node from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct and a node index. GET requests trigger no SSE events. Eyre returns a 200 response.

Fetches the all channels which the ship is a member of. Takes an UrbitEx.Session struct. GET requests trigger no SSE events. Eyre returns a 200 response. Function returns a list of UrbitEx.Resource structs. You can convert the graph to a list with UrbitEx.Graph.to_list/1

Link to this function

fetch_newest(session, resource, count)

View Source

Fetches latest nodes from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and a message count integer. Count limits appears to be 999. You can pass it an index string optionally (passed index can have a "/" or not, doesn't matter). This is the endpoint Landscape uses to render the chat. But it works fine with Notebooks or Collections too. GET requests trigger no SSE events. Eyre returns a 200 response. Function returns a graph (not a list!) of UrbitEx.Node structs, according to count requested. You can convert the graph to a list with UrbitEx.Graph.to_list/1

Link to this function

fetch_older_than(session, resource, index, count)

View Source

Fetches nodes from a channel which are older than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an index string (passed index can have a "/" or not, doesn't matter) and a message count integer. GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

fetch_oldest(session, resource, count)

View Source

Fetches oldest nodes from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and a message count integer. GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

fetch_subset(session, resource, start_index, end_index)

View Source

Fetches nodes from a channel which are older than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and two index strings, start and finish. GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

fetch_tag_queries(session)

View Source

Fetches tag queries. Takes an UrbitEx.Session struct. GET requests trigger no SSE events. Eyre returns a 200 response. Not sure what this is about.

Fetches tags. Takes an UrbitEx.Session struct. GET requests trigger no SSE events. Eyre returns a 200 response. Not sure what this is about.

Link to this function

fetch_whole_graph(session, resource)

View Source

Fetches the whole node graph from a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. This is the endpoint Landscape uses to render Notebooks and Collections. You can run it on a Chat but it'll timeout with big ones (over 999 nodes?). GET requests trigger no SSE events. Eyre returns a 200 response. Function returns a graph (not a list!) of UrbitEx.Node structs, according to count requested. You can convert the graph to a list with UrbitEx.Graph.to_list/1

Link to this function

fetch_younger_than(session, resource, index, count)

View Source

Fetches nodes from a channel which are younger than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, an index string (passed index can have a "/" or not, doesn't matter) and a message count integer. GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

join_channel(session, resource)

View Source

Joins a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers two graph-update event, one with a list of keys and for add-graph. Eyre returns a 200 response.

Link to this function

leave_channel(session, resource)

View Source

Leaves a channel. Takes an UrbitEx.Session struct and an UrbitEx.Resource struct. Triggers one graph-update event. Eyre returns a 200 response.

Link to this function

send_message(session, resource, message, custom \\ nil)

View Source

Send message to a chat channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a message string, and an optional custom list of token maps. Graph Store posts tokens can be text, mention, url, code or reference. In elixir a valid content list would look like [%{text: title}, %{url: "https://urbitasia.com"}, %{mention: "~mirtyl-wacdec"}] If no custom tokens are given, the function uses the default tokenizer used by Landscape. A custom tokenizer can be used to format text for custom clients without need for a custom backend. Triggers one graph-update event (the message itself). Eyre returns a 200 response.

Link to this function

start_dm(session, target)

View Source

Starts a Direct Message with a ship. Takes an UrbitEx.Session struct and an Urbit ID to invite. Just syntactic sugar over create_private_channel above. Follows Landscape naming convention.