diff options
| author | Matias Linares <matiaslina@gmail.com> | 2021-01-11 22:48:16 -0300 |
|---|---|---|
| committer | Matias Linares <matiaslina@gmail.com> | 2021-01-11 22:48:16 -0300 |
| commit | f6397392c4fc88d1e9335bbbc4f91d8cb2f29368 (patch) | |
| tree | dddb106193d48ca078946d2edb403ef75faca9dd /docs/client.pod6 | |
| parent | 14551a46b61a78a55cacf282e0534a1938215467 (diff) | |
| parent | 289165e26df8830a15b6df1a63321583a2e67499 (diff) | |
| download | perl6-matrix-client-f6397392c4fc88d1e9335bbbc4f91d8cb2f29368.tar.gz | |
Merge branch 'documentation'
Diffstat (limited to 'docs/client.pod6')
| -rw-r--r-- | docs/client.pod6 | 305 |
1 files changed, 0 insertions, 305 deletions
diff --git a/docs/client.pod6 b/docs/client.pod6 deleted file mode 100644 index ba1f2e1..0000000 --- a/docs/client.pod6 +++ /dev/null @@ -1,305 +0,0 @@ -=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 |