aboutsummaryrefslogtreecommitdiff
path: root/docs/Matrix/Client/Room.rakudoc
blob: bd0f6fd39a27946b28a410a1168ff251bc73fd8f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
=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 read-marker

    method read-marker(Str:D $fully-read, Str $read?)

Sets the position of the read marker for this room, and optionally the
read receipt's location.

The C<$fully-read> and C<$read> parameters are event ids where the
markers will be placed.

=head2 typing

    method typing(Bool $typing, Str :$user-id!, Int :$timeout)

Sends a typing event to the server telling that C<$user-id> is typing
or not (depending on C<$typing> argument).

The C<$timeout> parameter is optional for this endpoint.

=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