From c5e5856fab53af27e085bb65ba9eeacd2def1e6e Mon Sep 17 00:00:00 2001 From: Matias Linares Date: Wed, 5 Jun 2019 00:50:35 -0300 Subject: Upgrade documentation --- docs/client.pod6 | 58 ++++++++++++++++----- docs/requester.pod6 | 66 ++++++++++++++++++++++++ docs/responses.pod6 | 122 ++++++++++++++++++++++++++++++++++++++++++++ docs/usage.pod6 | 41 +++++++++++++++ docs/x-matrix-response.pod6 | 23 +++++++++ 5 files changed, 296 insertions(+), 14 deletions(-) create mode 100644 docs/requester.pod6 create mode 100644 docs/responses.pod6 create mode 100644 docs/usage.pod6 create mode 100644 docs/x-matrix-response.pod6 diff --git a/docs/client.pod6 b/docs/client.pod6 index 302e99b..ba1f2e1 100644 --- a/docs/client.pod6 +++ b/docs/client.pod6 @@ -2,25 +2,55 @@ =TITLE class Matrix::Client -=SUBTITLE Client API for Matrix +=SUBTITLE matrix.org client - class Matrix::Client does Matrix::Client::Requester {} +=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. +On server errors, all methods will throw a L exception. -=head1 Methods +=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 to make authorized +passed to the constructor, the client needs to call L<#login> to make authorized calls to the API. =head2 login @@ -33,7 +63,7 @@ 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 +On a failed login attempt, a L is raised with a code of C<“M_FORBIDDEN”> =head2 logout @@ -51,7 +81,7 @@ 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 +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. @@ -63,7 +93,7 @@ with one of the following Cs: method profile(Str :$user-id?) Get the combined profile information for this user. With no C<$user-id> -L will provide the profile data associated with the client +L<#profile> will provide the profile data associated with the client account. It returns a C that can contains C and/or C. @@ -125,10 +155,10 @@ must be C<“online”>, C<“offline”> or C<“unavailable”>. 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. +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. +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 @@ -217,11 +247,11 @@ L. The room alias must be in the form -C, otherwise it will raise a L with +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. +raise a L with a C code. =head2 add-room-alias @@ -248,8 +278,8 @@ Uploads a file to the server. It returns the MXC URI to the uploaded content. 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 request again. The C<$sync-filter> is the same parameter that -will be passed to L method to filter out the useful events. +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: diff --git a/docs/requester.pod6 b/docs/requester.pod6 new file mode 100644 index 0000000..6710948 --- /dev/null +++ b/docs/requester.pod6 @@ -0,0 +1,66 @@ +=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/responses.pod6 b/docs/responses.pod6 new file mode 100644 index 0000000..7515d39 --- /dev/null +++ b/docs/responses.pod6 @@ -0,0 +1,122 @@ +=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/usage.pod6 b/docs/usage.pod6 new file mode 100644 index 0000000..03454d1 --- /dev/null +++ b/docs/usage.pod6 @@ -0,0 +1,41 @@ +=begin pod +=head1 Before we begin… + +This guide will be a port from L +by the Matrix team. + +=head1 Making a Matrix Client + +Let's explore how we would make a very simple Matrix client, with the only ability to perform an initial +sync, and get the member list and the timeline for rooms of our choice. + +This guide will cover: + +=item Login +=item Simple syncing +=item Listening for timeline events +=item Sending messages to rooms +=item How to respond to specific messages + +=head2 Preparing the project + +Before we start, make sure you have perl6 and zef installed. My sugestion is to install +L and follow the instructions. + +Once you're ready, the first thing is to install +L with C + +=begin code +zef install Matrix::Client +=end code + +And now we can include it on our source exaclty as expected. + +=begin code +use Matrix::Client; +=end code + +=head2 Login with an access token + + +=end pod \ No newline at end of file diff --git a/docs/x-matrix-response.pod6 b/docs/x-matrix-response.pod6 new file mode 100644 index 0000000..d93c263 --- /dev/null +++ b/docs/x-matrix-response.pod6 @@ -0,0 +1,23 @@ +=begin pod + +=TITLE X::Matrix::Response + +=SUBTITLE Error querying the matrix server + + + class X::Matrix::Response is Exception {} + +Error class when the matrix server returns an error code (4XX). + +=head1 METHODS + +=head2 code + +Returns the HTTP error code. + +=head2 error + +Returns a C with the matrix error. A full list of error codes can be +found in the L. + +=end pod \ No newline at end of file -- cgit v1.2.3-70-g09d2