diff options
Diffstat (limited to 'docs/Matrix/Client.rakudoc')
| -rw-r--r-- | docs/Matrix/Client.rakudoc | 305 |
1 files changed, 305 insertions, 0 deletions
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<https://matrix.org>, + :access-token<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<body>; + } + } + +=head1 DESCRIPTION + + Class Matrix::Client does Matrix::Client::Requester {} + +The main object in the module. The C<Matrix::Client> 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<X::Matrix::Response|x-matrix-response.html> exception. + +=head1 METHODS + +=head2 new + + sub new(Str :$home-server, Str :$access-token?, Str :$device-id?) + +Creates a C<Matrix::Client> 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<password>. If C<device-id> is setted +before the C<login> call, it will register that C<device-id> in the server +invalidating any previously associated access token to this C<device-id>. +Otherwise the home server will auto-generate one. + +On a failed login attempt, a L<X::Matrix::Response|x-matrix-response.html> 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<user> 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<X::Matrix::Response|x-matrix-response.html> is raised +with one of the following C<code>s: + +=item C<M_USER_IN_USE> The desired user ID is already taken. +=item C<M_INVALID_USERNAME>: The desired user ID is not a valid user name. +=item C<M_EXCLUSIVE>: 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<Hash> that can contains C<avatar_url> and/or C<displayname>. + +=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<IO::Path> 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<Matrix::Response::Sync|responses.html#Sync> 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<next-batch> in the L<Matrix::Response::Sync|responses.html#sync>. + +The C<sync-filter> is the filter that will be applied to the sync. It will encode +it to a JSON string if it isn't a C<Str> already. For more information about +filters you can check the L<official spec|https://matrix.org/docs/spec/client_server/r0.3.0.html#filtering> + + # 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<Str> for a room alias. +=item name: A C<Str> for the room name. +=item topic: A C<Str> for the room topic. +=item invite: A list of C<Str> 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<Bool> 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<here|https://matrix.org/docs/spec/client_server/r0.3.0.html#post-matrix-client-r0-createroom> + +The C<$public> argument sets the C<visibility> to “public”, giving precedence to the C<visibility> +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</join/{roomIdOrAlias}|https://matrix.org/docs/spec/client_server/r0.3.0.html#post-matrix-client-r0-join-roomidoralias> +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<Seq> with the joined rooms within the client. + +=head2 public-rooms + + method public-rooms() + +Lists the public rooms on the server. + +B<Note>: 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<send> method +only sends C<“m.text”> events. In the future it will be extended to support all the +L<Room events|https://matrix.org/docs/spec/client_server/r0.3.0.html#room-events>. + +=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<localname:domain>, otherwise it will raise a L<X::Matrix::Response|x-matrix-response.html> with +the proper message and C<M_UNKNOWN> error code. + +If there's no room with the C<$room-alias> in the server directory, it will +raise a L<X::Matrix::Response|x-matrix-response.html> with a C<M_NOT_FOUND> 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<Supply> that emits L<Matrix::Response::StateEvent> 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 |