Merge branch 'documentation'

4 files changed, 413 insertions, 0 deletions

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<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>.
+
+=head3 message
+
+    method message(--> Str)
+
+Returns the exception message.
+
+=head1 X::Matrix::MXCParse
+
+Error while parsing a L<Matrix Content (MXC) URI|https://matrix.org/docs/spec/client_server/r0.6.1#matrix-content-mxc-uris>.
+
+    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<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/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<Matrix::Client::Room> is a shortcut to all the C</rooms/:id> endpoints. It
+does the role as L<Matrix::Client::Requester> 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<Matrix::Client>.
+
+=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<m.room.name> 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<Matrix::Response::RoomEvent>.
+
+=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<Seq>
+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<avatar_url>      # OUTPUT: «mxc://matrix.deprecated.org/NdSvF..»
+    say $member.values<display_name>    # 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<Matrix::Response::Messages> with the messages from
+C<$from>. This token can be obtained from a C<prev_batch> token
+returned for each room by the sync API, or from a C<start> or C<end>
+attributes from L<Matrix::Response::Messages>.
+
+=head2 members
+
+    method members(:$at, Str :$membership, Str :$not-membership --> Seq)
+
+Get the list of members for this room. This returns a C<Seq> of
+L<Matrix::Response::MemberEvent>.
+
+=head2 send
+
+    method send(Str $body!, Str :$type? = "m.text")
+
+Sends a message to the room. It will return the C<event_id> 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<event_id> 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<Matrix::Client::Room> expects
+a room id (C<#032mf90f:matrix.org> for example), you need to use the
+L<join-room> method of C<Matrix::Client> 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