Upgrade documentation

author: Matias Linares <matiaslina@gmail.com> 2019-06-05 00:50:35 -0300
committer: Matias Linares <matiaslina@gmail.com> 2019-06-05 00:50:35 -0300
commit: c5e5856fab53af27e085bb65ba9eeacd2def1e6e (patch)
tree: ebf71494bc60bcda0fbf7c1ad4982db033300be3
parent: 4c007e0df300e7fb281fcadbcf707b71ed7e2483 (diff)
download: perl6-matrix-client-c5e5856fab53af27e085bb65ba9eeacd2def1e6e.tar.gz
5 files changed, 296 insertions, 14 deletions
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<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> exception.
+On server errors, all methods will throw a L<X::Matrix::Response|x-matrix-response.html> exception.
 
-=head1 Methods
+=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
+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<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
+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
@@ -51,7 +81,7 @@ 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
+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.
@@ -63,7 +93,7 @@ with one of the following C<code>s:
     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
+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>.
@@ -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<Matrix::Response::Sync> with the initial snapshot or delta.
+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>.
+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
@@ -217,11 +247,11 @@ L<Room events|https://matrix.org/docs/spec/client_server/r0.3.0.html#room-events
     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> with
+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<L::Matrix::Response> with a C<M_NOT_FOUND> code.
+raise a L<X::Matrix::Response|x-matrix-response.html> with a C<M_NOT_FOUND> 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<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.
+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<prev_content>
+=item C<state_key>
+
+=head1 Timeline
+
+
+       class Matrix::Response::Timeline { }
+
+=head2 Mapped keys
+
+=item events — Return a list of L<Matrix::Response::Event|#Event>
+=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<Matrix::Response::Event|#Event>
+=item Timeine — A L<Matrix::Response::Timeline|#Timeline>
+
+=head1 InviteInfo
+
+
+       class Matrix::Response::InviteInfo { }
+
+=head2 Mapped keys
+
+=item room-id — Str with the room id
+=item events — List of L<Matrix::Response::Event|#Event>
+
+=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<Matrix::Response::Event|#Event>
+=item joined-rooms — List of L<Matrix::Response::RoomInfo|#RoomInfo>
+=item invited-rooms — List of L<Matrix::Response::InviteInfo|#InviteInfo>
+
+
+=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<this guide|https://matrix.org/docs/guides/usage-of-the-matrix-js-sdk>
+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<rakudobrew|https://github.com/tadzik/rakudobrew> and follow the instructions.
+
+Once you're ready, the first thing is to install
+L<Matrix::Client|https://github.com/matiaslina/perl6-matrix-client> with C<zef>
+
+=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<Str> with the matrix error. A full list of error codes can be
+found in the L<matrix spec|https://matrix.org/docs/spec/client_server/r0.4.0.html#api-standards>.
+
+=end pod
+\ No newline at end of file
author	Matias Linares <matiaslina@gmail.com>	2019-06-05 00:50:35 -0300
committer	Matias Linares <matiaslina@gmail.com>	2019-06-05 00:50:35 -0300
commit	c5e5856fab53af27e085bb65ba9eeacd2def1e6e (patch)
tree	ebf71494bc60bcda0fbf7c1ad4982db033300be3
parent	4c007e0df300e7fb281fcadbcf707b71ed7e2483 (diff)
download	perl6-matrix-client-c5e5856fab53af27e085bb65ba9eeacd2def1e6e.tar.gz