aboutsummaryrefslogtreecommitdiff
path: root/docs/client.pod6
diff options
context:
space:
mode:
authorMatias Linares <matiaslina@gmail.com>2021-01-11 22:48:16 -0300
committerMatias Linares <matiaslina@gmail.com>2021-01-11 22:48:16 -0300
commitf6397392c4fc88d1e9335bbbc4f91d8cb2f29368 (patch)
treedddb106193d48ca078946d2edb403ef75faca9dd /docs/client.pod6
parent14551a46b61a78a55cacf282e0534a1938215467 (diff)
parent289165e26df8830a15b6df1a63321583a2e67499 (diff)
downloadperl6-matrix-client-f6397392c4fc88d1e9335bbbc4f91d8cb2f29368.tar.gz
Merge branch 'documentation'
Diffstat (limited to 'docs/client.pod6')
-rw-r--r--docs/client.pod6305
1 files changed, 0 insertions, 305 deletions
diff --git a/docs/client.pod6 b/docs/client.pod6
deleted file mode 100644
index ba1f2e1..0000000
--- a/docs/client.pod6
+++ /dev/null
@@ -1,305 +0,0 @@
-=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