Merge branch 'documentation'

author: Matias Linares <matiaslina@gmail.com> 2021-01-11 22:48:16 -0300
committer: Matias Linares <matiaslina@gmail.com> 2021-01-11 22:48:16 -0300
commit: f6397392c4fc88d1e9335bbbc4f91d8cb2f29368 (patch)
tree: dddb106193d48ca078946d2edb403ef75faca9dd /docs/Matrix
parent: 14551a46b61a78a55cacf282e0534a1938215467 (diff)
parent: 289165e26df8830a15b6df1a63321583a2e67499 (diff)
download: perl6-matrix-client-f6397392c4fc88d1e9335bbbc4f91d8cb2f29368.tar.gz
5 files changed, 718 insertions, 0 deletions
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<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|x-matrix-response.html> exception.
+
+=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
+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<password>. If C<device-id> is setted
+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|x-matrix-response.html> 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<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|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.
+=item C<M_INVALID_USERNAME>: The desired user ID is not a valid user name.
+=item C<M_EXCLUSIVE>: 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<Hash> that can contains C<avatar_url> and/or C<displayname>.
+
+=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<IO::Path> 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<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|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
+filters you can check the L<official spec|https://matrix.org/docs/spec/client_server/r0.3.0.html#filtering>
+
+    # 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<Str> for a room alias.
+=item name: A C<Str> for the room name.
+=item topic: A C<Str> for the room topic.
+=item invite: A list of C<Str> 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<Bool> 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<here|https://matrix.org/docs/spec/client_server/r0.3.0.html#post-matrix-client-r0-createroom>
+
+The C<$public> argument sets the C<visibility> to “public”, giving precedence to the C<visibility>
+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</join/{roomIdOrAlias}|https://matrix.org/docs/spec/client_server/r0.3.0.html#post-matrix-client-r0-join-roomidoralias>
+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<Seq> with the joined rooms within the client.
+
+=head2 public-rooms
+
+    method public-rooms()
+
+Lists the public rooms on the server. 
+
+B<Note>: 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<send> method
+only sends C<“m.text”> events. In the future it will be extended to support all the
+L<Room events|https://matrix.org/docs/spec/client_server/r0.3.0.html#room-events>.
+
+=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<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<X::Matrix::Response|x-matrix-response.html> with a C<M_NOT_FOUND> 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<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.
+
+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<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
author	Matias Linares <matiaslina@gmail.com>	2021-01-11 22:48:16 -0300
committer	Matias Linares <matiaslina@gmail.com>	2021-01-11 22:48:16 -0300
commit	f6397392c4fc88d1e9335bbbc4f91d8cb2f29368 (patch)
tree	dddb106193d48ca078946d2edb403ef75faca9dd /docs/Matrix
parent	14551a46b61a78a55cacf282e0534a1938215467 (diff)
parent	289165e26df8830a15b6df1a63321583a2e67499 (diff)
download	perl6-matrix-client-f6397392c4fc88d1e9335bbbc4f91d8cb2f29368.tar.gz