UrbitEx.API.Graph (UrbitEx v0.6.0) 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 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 nodes 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.

Checks if a node exists in a given 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 children of a node. Takes a Session struct, a Resource struct, the parent index you want to scry, and optional start and end indexes if you want to specify a range for children to be fetched. Also takes an optional options keyword list (see above). If passed an empty parent_index it will scry the root node (i.e. the channel itself).

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 any channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and an option keyword list. Option keys can be :count, with an integer value, for the number of nodes to be fetched (limits appears to be 999) and:replies, with a boolean value, to pass whether you want node replies to be included in the fetch. 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 withUrbitEx.Graph.to_list/1`

Fetches a single node from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a node index and an options keyword list (see above). 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, an index string (passed index can have a "/" or not, doesn't matter) and an options keyword list (see above). 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 an options keyword list (see above). 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, two index strings, start and finish, and an options keyword list (see above). 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 an options keyword list (see above). 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.

Posts a reply to a post in a feed channel. Takes a ession struct, a Resource struct, a message string, an index string of the node to reply to, and an optional custom list of token maps.

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 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 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_open_channel(session, title, name, description, type)

View Source
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_nodes(session, channel, resource, indices)

View Source

Deletes nodes 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

exists?(session, resource, index)

View Source

Checks if a node exists in a given 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.

Link to this function

fetch_archived_graph(session, resource)

View Source
Link to this function

fetch_children(session, resource, parent_index, start_index \\ "/", end_index \\ "/", opts \\ [])

View Source

Fetches children of a node. Takes a Session struct, a Resource struct, the parent index you want to scry, and optional start and end indexes if you want to specify a range for children to be fetched. Also takes an optional options keyword list (see above). If passed an empty parent_index it will scry the root node (i.e. the channel itself).

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, opts \\ [])

View Source

Fetches latest nodes from any channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and an option keyword list. Option keys can be :count, with an integer value, for the number of nodes to be fetched (limits appears to be 999) and:replies, with a boolean value, to pass whether you want node replies to be included in the fetch. 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 withUrbitEx.Graph.to_list/1`

Link to this function

fetch_node(session, resource, index, opts \\ [])

View Source

Fetches a single node from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, a node index and an options keyword list (see above). GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

fetch_older_than(session, resource, index, opts \\ [])

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 an options keyword list (see above). GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

fetch_oldest(session, resource, opts \\ [])

View Source

Fetches oldest nodes from a channel. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, and an options keyword list (see above). GET requests trigger no SSE events. Eyre returns a 200 response.

Link to this function

fetch_siblings(session, resource, index, type, opts)

View Source
Link to this function

fetch_subset(session, resource, start_index, end_index, opts \\ [])

View Source

Fetches nodes from a channel which are older than a given index. Takes an UrbitEx.Session struct, an UrbitEx.Resource struct, two index strings, start and finish, and an options keyword list (see above). 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, opts \\ [])

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 an options keyword list (see above). 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

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

View Source

Posts a message to a group feed. Alias of send_message/4.

Link to this function

reply_to_feed_post(session, resource, index, message, custom \\ nil)

View Source

Posts a reply to a post in a feed channel. Takes a ession struct, a Resource struct, a message string, an index string of the node to reply to, and an optional custom list of token maps.

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.