aboutsummaryrefslogtreecommitdiff
path: root/docs/Matrix/Client.rakudoc
diff options
context:
space:
mode:
authorMatias Linares <matiaslina@gmail.com>2021-01-11 22:19:00 -0300
committerMatias Linares <matiaslina@gmail.com>2021-01-11 22:19:00 -0300
commit9da9134f0b28c0e4c69537b54fd96dca3a66aaed (patch)
tree46a14da15beb95dd6f2c6b995b2dc6e7b6e94970 /docs/Matrix/Client.rakudoc
parente5e5211aab9e6c579eeb6e78673015dcc03bb666 (diff)
downloadperl6-matrix-client-9da9134f0b28c0e4c69537b54fd96dca3a66aaed.tar.gz
[DOC] .pod6 -> .rakudoc extension & better layout
Diffstat (limited to 'docs/Matrix/Client.rakudoc')
-rw-r--r--docs/Matrix/Client.rakudoc305
1 files changed, 305 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