diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/client.pod6 | 207 |
1 files changed, 207 insertions, 0 deletions
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<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> 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> 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> 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 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> 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>. + +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 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 |