From 9da9134f0b28c0e4c69537b54fd96dca3a66aaed Mon Sep 17 00:00:00 2001 From: Matias Linares Date: Mon, 11 Jan 2021 22:19:00 -0300 Subject: [DOC] .pod6 -> .rakudoc extension & better layout --- docs/Matrix/Client.rakudoc | 305 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 docs/Matrix/Client.rakudoc (limited to 'docs/Matrix/Client.rakudoc') diff --git a/docs/Matrix/Client.rakudoc b/docs/Matrix/Client.rakudoc new file mode 100644 index 0000000..ba1f2e1 --- /dev/null +++ b/docs/Matrix/Client.rakudoc @@ -0,0 +1,305 @@ +=begin pod + +=TITLE class Matrix::Client + +=SUBTITLE matrix.org client + +=head1 NAME + +Matrix::Client — Client API for Matrix.org + +=head1 SYNOPSIS + + use Matrix::Client; + + my Matrix::Client $client .= new( + :home-server, + :access-token + ); + + my $room = $client.joined-rooms.first; + $room.send("Hello from Matrix::Client"); + + + my $sync = $client.sync; + + for $response.joined-rooms -> $room { + say "Messages from {$room.name}" + for $room.timeline + .events + .grep(*.type eq 'm.room.message') -> $msg { + say $msg.content; + } + } + +=head1 DESCRIPTION + + 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<#login> 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<#profile> 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 presence + + method presence(Matrix::Client:D: $user-id? --> Matrix::Response::Presence) + +Query the presence status for an user. if no C<$user-id> is passed as argument, +it will return the presence of the user associated with the client. + +=head2 set-presence + + method set-presence(Matrix::Client:D: Str $presence, Str :$status-message = "") + +Sets the manually the presence of the client account. The C<$presence> argument +must be C<“online”>, C<“offline”> or C<“unavailable”>. + +=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 get-room-id + + method get-room-id($room-alias) + +Get the room id for an C<$room-alias>. The room alias must be in the form +C, otherwise it will raise a L with +the proper message and C error code. + +If there's no room with the C<$room-alias> in the server directory, it will +raise a L with a C code. + +=head2 add-room-alias + + method add-room-alias($room-id, $room-alias) + +Add the C<$room-alias> to the C<$room-id>. + +=head2 remove-room-alias + + method remove-room-alias($room-alias) + +Remove a mapping of C<$room-alias> to room ID. The room ID isn't a must and +the servers may choose to implement additional access control for this endpoint. + +=head2 upload + + method upload(IO::Path $path, Str $filename?) + +Uploads a file to the server. It returns the MXC URI to the uploaded content. + +=head2 run + + method run(Int :$sleep = 10, :$sync-filter? --> Supply) + +Returns a C that emits L with the last +events. The C<$sleep> parameter is to sleep for that amount of seconds before +making a L<#sync> request again. The C<$sync-filter> is the same parameter that +will be passed to L<#sync> method to filter out the useful events. + +This can be useful to turn something like: + + my $since; + loop { + $response = $client.sync(:$since); + $since = $response.next-batch; + + for $response.joined-rooms -> $room { + for $room.timeline.event -> $event { + # Do something useful with $event + } + } + } + +into: + + my $sup = $client.run(); + react whenever $sup -> $event { + # Do something useful with $event + } + +=end pod -- cgit v1.2.3-70-g09d2