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 +++++++++++++++++++++++++++++++++++ docs/Matrix/Client/Exception.rakudoc | 52 ++++++ docs/Matrix/Client/Requester.rakudoc | 65 ++++++++ docs/Matrix/Client/Response.rakudoc | 121 ++++++++++++++ docs/Matrix/Client/Room.rakudoc | 175 ++++++++++++++++++++ 5 files changed, 718 insertions(+) create mode 100644 docs/Matrix/Client.rakudoc create mode 100644 docs/Matrix/Client/Exception.rakudoc create mode 100644 docs/Matrix/Client/Requester.rakudoc create mode 100644 docs/Matrix/Client/Response.rakudoc create mode 100644 docs/Matrix/Client/Room.rakudoc (limited to 'docs/Matrix') 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 diff --git a/docs/Matrix/Client/Exception.rakudoc b/docs/Matrix/Client/Exception.rakudoc new file mode 100644 index 0000000..f814bbc --- /dev/null +++ b/docs/Matrix/Client/Exception.rakudoc @@ -0,0 +1,52 @@ +=begin pod + +=TITLE Matrix::Client::Exception + +=SUBTITLE Module for all exceptions. + +=head1 X::Matrix::Response + +Error querying the matrix server + + + class X::Matrix::Response is Exception + +Error class when the matrix server returns an error code (4XX). + +=head2 METHODS + +=head3 code + +Returns the HTTP error code. + +=head3 error + +Returns a C with the matrix error. A full list of error codes can be +found in the L. + +=head3 message + + method message(--> Str) + +Returns the exception message. + +=head1 X::Matrix::MXCParse + +Error while parsing a L. + + class X::Matrix::MXCParse is Exception + + +=head2 METHODS + +=head3 code + +Returns the URI that failed to parse. + +=head3 message + + method message(--> Str) + +Returns the exception message. + +=end pod diff --git a/docs/Matrix/Client/Requester.rakudoc b/docs/Matrix/Client/Requester.rakudoc new file mode 100644 index 0000000..2c0215d --- /dev/null +++ b/docs/Matrix/Client/Requester.rakudoc @@ -0,0 +1,65 @@ +=begin pod + +=TITLE role Matrix::Client::Requester + +=SUBTITLE Role for HTTP requests + + role Matrix::Client::Requester { } + +Role that gives the base API for objects that interacts to the matrix server. The +attributes that can be set can be: + +=head1 Attributes + +=head2 Str home-server + +The url of the home-server. + +=head2 Str access-token + +access token to make authorized calls to the matrix server. + +=head2 Str url-prefix + +Prefix to all the paths used in the methods. + +=head1 Methods + +=head2 get + + method get(Str $path, :$media = False, *%data) + +Do a GET to C<$path>. + +All the C<*%data> is used to build the query params for the url. + +=head2 post + + multi method post(Str $path, Str $params, :$media = False) + multi method post(Str $path, :$media = False, *%params) + +Do a POST to C<$path> with C<$params> as JSON body. With the +named C<*%params>, those are parameters are converted into JSON. + +=head2 post-bin + + method post-bin(Str $path, Buf $buf, :$content-type) + +Do a POST to C<$path> with binary data in the body. + +=head2 put + + +multi method put(Str $path, Str $params) +multi method put(Str $path, *%params) + +Do a PUT to C<$path> with C<$params> as JSON body. With the named +C<*%params>, those parameters are converted into JSON. + +=head2 delete + + method delete(Str $path) + +Do a DELETE to C<$path>. + +=end pod \ No newline at end of file diff --git a/docs/Matrix/Client/Response.rakudoc b/docs/Matrix/Client/Response.rakudoc new file mode 100644 index 0000000..e0bed14 --- /dev/null +++ b/docs/Matrix/Client/Response.rakudoc @@ -0,0 +1,121 @@ +=begin pod + +=TITLE Matrix Responses + +=SUBTITLE Wrappers for HTTP responses + +=head1 Event + + class Matrix::Response::Event { } + +Common contents of a response. + +=head2 Mapped keys + +=item content +=item type + +=head1 RoomEvent + + + class Matrix::Response::RoomEvent is Matrix::Response::Event { } + +A single event for a room + +=head2 Mapped keys + +=item sender +=item origin_server_ts +=item event_id +=item room_id + +=head2 Methods + +=head3 id + + method id + +Returns the event_id + +=head3 timestamp + + method timestamp + +Returns the origin_server_ts + +=head3 room-id + + method room-id + +returns the room_id + + +=head1 StateEvent + + + class Matrix::Response::StateEvent is Matrix::Response::RoomEvent { } + +=head2 Mapped keys + +=item C +=item C + +=head1 Timeline + + + class Matrix::Response::Timeline { } + +=head2 Mapped keys + +=item events — Return a list of L +=item limited +=item prev-batch + + +=head1 RoomInfo + + + class Matrix::Response::RoomInfo { } + +=head2 Mapped keys + +=item room-id — Str with the room id +=item state — List of L +=item Timeine — A L + +=head1 InviteInfo + + + class Matrix::Response::InviteInfo { } + +=head2 Mapped keys + +=item room-id — Str with the room id +=item events — List of L + +=head1 Sync + + + class Matrix::Response::Sync { } + +=head2 Mapped keys + +=item next-batch — Str with the hash for the next sync batch +=item presence — List of L +=item joined-rooms — List of L +=item invited-rooms — List of L + + +=head1 Presence + + + class Matrix::Response::Presence { } + +=head2 Mapped keys + +=item presence +=item last-active-ago +=item status-message +=item currently-active + +=end pod \ No newline at end of file diff --git a/docs/Matrix/Client/Room.rakudoc b/docs/Matrix/Client/Room.rakudoc new file mode 100644 index 0000000..f186583 --- /dev/null +++ b/docs/Matrix/Client/Room.rakudoc @@ -0,0 +1,175 @@ +=begin pod + +=TITLE class Matrix::Client::Room + +=SUBTITLE Room requester + + class Matrix::Client::Room does Matrix::Client::Requester {} + +The C is a shortcut to all the C endpoints. It +does the role as L so one can instantiate a Room with +the one's access token and the room id to make requests directly to this room +without the need for a L. + +=head1 Example + + my $room-id = "!pGOClvZafMH:matrix.server.com"; + my $home-server = "https://matrix.server.com"; + my $access-token = "…"; + + my Matrix::Client::Room $room .= new( + :$access-token, + :$home-server, + :id($room-id) + ); + + say $room.name; + +=head1 Methods + +=head2 name + + method name(--> Str) + +Returns the name of the room. If no C was emmited (i.e.: no name +was set for this room), then an empty string is returned. + +=head2 fallback-name + + method fallback-name(--> Str) + +Return a name for the room with the members of the room. Use this if +the room doesn't have a name set or in 1-1 chats. + +Example: + + my $room = Matrix::Client::Room $room .= new( + :$access-token, :$home-server, :id('#34df12:matrix.org') + ); + say 'Room name: ' ~ $room.name # OUTPUT: «Room name: » + say 'Room name: ' ~ $room.fallback-name # OUTPUT: «Room name: Alice and Bob» + +=head2 aliases + + method aliases(--> List) + +Get a list of aliases maintained by the local server for the given room. + +=head2 event + + method event(Str $event-id --> Matrix::Response::RoomEvent) + +Get a single event based on the C<$event-id>. Returns a L. + +=head2 state + + multi method state(--> Seq) + multi method state(Str $event-type, Str $state-key = "") + +Get the state events for the current state of a room. it will return a C +for every event on that room. + +If an C<$event-type> is passed, the return value will be the value of that +single event. + +C<$state-key> is the key of the state to look up. + +=head2 joined-members + + method joined-members() + +Returns the data for the members of the room. + +Example: + + my $room = Matrix::Client::Room $room .= new( + :$access-token, :$home-server, :id('#34df12:matrix.org') + ); + my $member = $room.joined-members.head; + # the key is the matrix id + say $member.key # OUTPUT: «@meeple:matrix.deprecated.org» + say $member.values # OUTPUT: «mxc://matrix.deprecated.org/NdSvF..» + say $member.values # OUTPUT: «meeple» + +=head2 messages + + method messages( + Str:D :$from!, Str :$to, + Str :$dir where * eq 'f'|'b' = 'f', + Int :$limit = 10, :%filter + --> Matrix::Response::Messages + ) + +Return a L with the messages from +C<$from>. This token can be obtained from a C token +returned for each room by the sync API, or from a C or C +attributes from L. + +=head2 members + + method members(:$at, Str :$membership, Str :$not-membership --> Seq) + +Get the list of members for this room. This returns a C of +L. + +=head2 send + + method send(Str $body!, Str :$type? = "m.text") + +Sends a message to the room. It will return the C for this message. + +=head2 send-state + + method send-state(Str:D $event-type, :$state-key = "", *%args --> Str) + +Send a state event to the server. The event will be overwritten if the +C<$event-type>, C<$state-key> and the arguments all match with a state in the +server. + +It will return the C for this state change. + +=head2 invite + + method invite(Str $user-id) + +Invite a user to the room. + +=head2 join + + method join() + +Join the room. As the creation of the C expects +a room id (C<#032mf90f:matrix.org> for example), you need to use the +L method of C to join by an alias. + +=head2 leave + + method leave() + +Leaves the room. + +=head2 forget + + method forget() + +Stop a user of remembering this particular room. + +=head2 kick + + method kick(Str $user-id, Str $reason = "") + +Kick an user of this room. + +=head2 ban + + method ban(Str $user-id, $reason = "") + +Ban an user of this room. + +=head2 unban + + method unban(Str $user-id) + +Unban a user of this room. + +=end pod -- cgit v1.2.3-70-g09d2