From 738766a38ec43a3de904561a9669fe9eb6be3408 Mon Sep 17 00:00:00 2001 From: Matias Linares Date: Tue, 5 Jun 2018 23:52:35 -0300 Subject: Add client documentation. --- docs/client.pod6 | 207 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/client.pod6 diff --git a/docs/client.pod6 b/docs/client.pod6 new file mode 100644 index 0000000..a441b7c --- /dev/null +++ b/docs/client.pod6 @@ -0,0 +1,207 @@ +=begin pod + +=TITLE class Matrix::Client + +=SUBTITLE Client API for Matrix + + class Matrix::Client does Matrix::Client::Requester {} + +The main object in the module. The C is used to talk to a +Matrix home server abstracting the HTTP requests. + +The client is used for example to join rooms, receive/send messages, etc. + +On server errors, all methods will throw a L exception. + +=head1 Methods + +=head2 new + + sub new(Str :$home-server, Str :$access-token?, Str :$device-id?) + +Creates a C pointing to a home server. If no C<$access-token> is +passed to the constructor, the client needs to call L to make authorized +calls to the API. + +=head2 login + + multi method login(Str $username, Str $password) + multi method login(Str :$username, Str :$password) + +Logs in with the C<$username> and C. If C is setted +before the C call, it will register that C in the server +invalidating any previously associated access token to this C. +Otherwise the home server will auto-generate one. + +On a failed login attempt, a L is raised with a code +of C<“M_FORBIDDEN”> + +=head2 logout + + method logout() + +Invalidates the access token, so that it can no longer be used for authorization. + +=head2 register + + method register($username, $password, Bool :$bind-email? = False) + +Register a B account in the home server. + +If C<$bind-email> is true, the server binds the email used for authentication +to the Matrix ID with the ID Server. + +In case there's an error with the registration, a L is raised +with one of the following Cs: + +=item C The desired user ID is already taken. +=item C: The desired user ID is not a valid user name. +=item C: The desired user ID is in the exclusive namespace claimed by an application service. + +=head2 profile + + method profile(Str :$user-id?) + +Get the combined profile information for this user. With no C<$user-id> +L will provide the profile data associated with the client +account. + +It returns a C that can contains C and/or C. + +=head2 display-name + + method display-name(Str :$user-id?) + +Get the display-name of the C<$user-id>. With no C<$user-id> it will return +the display name associated with the client account. + +=head2 change-display-name + + method change-display-name(Str:D $display-name!) + +Change the client account display name. + +=head2 avatar-url + + method avatar-url(Str :$user-id?) + +Get the avatar url for a given C<$user-id>. With no C<$user-id> it will return +the avatar url associated with the client account. + +=head2 change-avatar + + multi method change-avatar(IO::Path $avatar) + multi method change-avatar(Str:D $mxc-url!) + +Changes the avatar for the client account. + +Passing a C to the method will upload the image to the server +and then set that uploaded image as avatar. + +=head2 whoami + + method whoami + +Returns the user id of the client account. + +=head2 sync + + multi method sync(:$since = "") + multi method sync(Str :$sync-filter, Str :$since = "") + multi method sync(Hash :$sync-filter is copy, :$since = "") + +Gets the client's state with the latest state on the server. It returns +a L with the initial snapshot or delta. + +C<$since> is necessary to get the incremental deltas to the states. The C<$since> +value is retrieved from the C in the L. + +The C is the filter that will be applied to the sync. It will encode +it to a JSON string if it isn't a C already. For more information about +filters you can check the L + + # Filter to apply to the sync. + my $sync-filter = { room => timeline => limit => 1 }; + my $sync = $client.sync(:$sync-filter); + # Get the next batch to get a delta on the sync. + my $since = $sync.next-batch; + + # This will return the same $sync as above. + my $same-sync = $client.sync(:$sync-filter); + # This won't + my $new-sync = $client.sync(:$sync-filter, :$since); + + +=head2 create-room + + method create-room( + Bool :$public = False, + *%args --> Matrix::Client::Room + ) + +Create a room in the home server. Possible arguments for C<*%args> are: + +=item visibility: C<“public”> or C<“private”>. +=item room_alias_name: A C for a room alias. +=item name: A C for the room name. +=item topic: A C for the room topic. +=item invite: A list of C of user ids to invite to the room. +=item preset: C<“private_chat”>, C<“trusted_private_chat”> or C<“public_chat”>. +=item is_direct: A C to make the room as a direct chat. + +The parameters can be typed with C<-> instead C<_> for style purposes, the method +will change those characters to match the Matrix API. The list can be found +L + +The C<$public> argument sets the C to “public”, giving precedence to the C +in C<%*args>. + +=head2 join-room + + method join-room($room-id!) + +Joins a room. + +The C<$room-id> can be either a room id (!superhash:server) or an alias (#alias:server) +since it uses the L +endpoint. + +=head2 leave-room + + method leave-room($room-id) + +Leaves a room. + +The C<$room-id> must be a room id (!superhash:server). + +=head2 joined-rooms + + method joined-rooms(--> Seq) + +Returns a C with the joined rooms within the client. + +=head2 public-rooms + + method public-rooms() + +Lists the public rooms on the server. + +B: Right now this is returning the parsed JSON from the response. + +=head2 send + + method send(Str $room-id, Str $body, :$type? = "m.text") + +Send a message event to a room. + +C<$room-id> must be a room id with the form “!hast:server”. As for now the C method +only sends C<“m.text”> events. In the future it will be extended to support all the +L. + +=head2 upload + + method upload(IO::Path $path, Str $filename?) + +Uploads a file to the server. It returns the MXC URI to the uploaded content. + +=end pod -- cgit v1.2.3-70-g09d2