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/client.pod6 | 305 ------------------------------------------------------- 1 file changed, 305 deletions(-) delete mode 100644 docs/client.pod6 (limited to 'docs/client.pod6') 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, - :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