Mercurial > prosody-modules

comparison mod_groups_internal/README.md @ 6155:d0a117e11cb8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_groups_internal: Improve Markdown structure of documentation
author Rémi Bardon <remi@remibardon.name>
date Fri, 31 Jan 2025 02:16:55 +0100
parents 62ff93af69d5
children
comparison
equal deleted inserted replaced
6154:62ff93af69d5 6155:d0a117e11cb8
33 33
34 ## Usage 34 ## Usage
35 35
36 ### Exposed functions 36 ### Exposed functions
37 37
38 #### `create(group_info, create_default_muc, group_id)` {#create} 38 - #### `create(group_info, create_default_muc, group_id)` {#create}
39 39
40 Creates a new group, optionally creating a default MUC chat on [`groups_muc_host`](#configuration). 40 Creates a new group, optionally creating a default MUC chat on [`groups_muc_host`](#configuration).
41 41
42 **Parameters:** 42 **Parameters:**
43 43
44 1. `group_info: { name: string }` 44 1. `group_info: { name: string }`
45 2. `create_default_muc: boolean | nil`: Whether or not to create the default MUC chat. Defaults to `false`. 45 2. `create_default_muc: boolean | nil`: Whether or not to create the default MUC chat. Defaults to `false`.
46 3. `group_id: string | nil`: The desired group JID node part. Defaults to [`util.id.short`](https://prosody.im/doc/developers/util/id) (9-chars URL-safe base64). 46 3. `group_id: string | nil`: The desired group JID node part. Defaults to [`util.id.short`](https://prosody.im/doc/developers/util/id) (9-chars URL-safe base64).
47 47
48 **Returns:** `group_id: string | nil, error: string` 48 **Returns:** `group_id: string | nil, error: string`
49 49
50 #### `get_info(group_id)` {#get_info} 50 - #### `get_info(group_id)` {#get_info}
51 51
52 Retrieves information about a group. 52 Retrieves information about a group.
53 53
54 **Parameters:** 54 **Parameters:**
55 55
56 1. `group_id: string`: Node part of the group's JID. 56 1. `group_id: string`: Node part of the group's JID.
57 57
58 **Returns:** 58 **Returns:**
59 59
60 ```lua 60 ```lua
61 group_info: { 61 group_info: {
62 name: string,
63 muc_jid: string | nil
64 }
65 | nil
66 ```
67
68 #### `set_info(group_id, info)` {#set_info}
69
70 Allows one to change a group's name. If `muc_jid` is specified, this function will also update the group chat's name.
71
72 **Parameters:**
73
74 1. `group_id: string`: Node part of the group's JID.
75 2. `group_info: { name: string, muc_jid: string | nil }`
76
77 **Returns:** `true | nil, error: string`
78
79 #### `get_members(group_id)` {#get_members}
80
81 Retrieves the list of members in a given group.
82
83 **Parameters:**
84
85 1. `group_id: string`: Node part of the group's JID.
86
87 **Returns:** `group_members: {string}`
88
89 #### `exists(group_id)` {#exists}
90
91 Returns whether or not a group exists.
92
93 **Parameters:**
94
95 1. `group_id: string`: Node part of the group's JID.
96
97 **Returns:** `group_exists: boolean`
98
99 #### `get_user_groups(username)` {#get_user_groups}
100
101 Lists which groups a given user is a part of.
102
103 **Parameters:**
104
105 1. `username: string`: Node part of the user's JID.
106
107 **Returns:** `user_groups: {string}`
108
109 #### `delete(group_id)` {#delete}
110
111 Deletes a given group and its associated group chats.
112
113 **Parameters:**
114
115 1. `group_id: string`: Node part of the group's JID.
116
117 **Returns:** `true | nil, error: string`
118
119 #### `add_member(group_id, username, delay_update)` {#add_member}
120
121 Adds a member to a given group, optionally delaying subscriptions until [`sync`](#sync) is called.
122
123 ::: {.alert .alert-info}
124 This function emits a [`group-user-added`](#group-user-added) event on successful execution.
125 :::
126
127 **Parameters:**
128
129 1. `group_id: string`: Node part of the group's JID.
130 2. `delay_update: boolean | nil`: Do not update subscriptions until [`sync`](#sync) is called. Defaults to `false`.
131
132 **Returns:** `true | nil, error: string`
133
134 #### `remove_member(group_id, username)` {#remove_member}
135
136 Removes a member from a given group.
137
138 ::: {.alert .alert-info}
139 This function emits a [`group-user-removed`](#group-user-removed) event on successful execution.
140 :::
141
142 **Parameters:**
143
144 1. `group_id: string`: Node part of the group's JID.
145 2. `username: string`: Node part of the user's JID.
146
147 **Returns:** `true | nil, error: string`
148
149 #### `sync(group_id)` {#sync}
150
151 Updates group subscriptions (used to apply pending changes from [`add_member`](#add_member)).
152
153 **Parameters:**
154
155 1. `group_id: string`: Node part of the group's JID.
156
157 **Returns:** `nil`
158
159 #### `add_group_chat(group_id, name)` {#add_group_chat}
160
161 Creates a new group chat for a given group.
162
163 ::: {.alert .alert-info}
164 Its JID will be `<`[`util.id.short`](https://prosody.im/doc/developers/util/id)`>@<`[`option:groups_muc_host`](#configuration)`>`.
165 :::
166
167 **Parameters:**
168
169 1. `group_id: string`: Node part of the group's JID.
170 2. `name: string`: Desired name of the group chat.
171
172 **Returns:**
173
174 ```lua
175 muc: {
176 jid: string,
177 name: string,
178 }
179 | nil, error: string
180 ```
181
182 #### `remove_group_chat(group_id, muc_id)` {#remove_group_chat}
183
184 Removes a group chat for a given group.
185
186 ::: {.alert .alert-info}
187 This function emits a [`group-chat-removed`](#group-chat-removed) event on successful execution.
188 :::
189
190 **Parameters:**
191
192 1. `group_id: string`: Node part of the group's JID.
193 2. `muc_id: string`: Node part of the MUC JID.
194
195 **Returns:** `true | nil, error: string`
196
197 #### `get_group_chats(group_id)` {#get_group_chats}
198
199 Lists group chats associated to a given group.
200
201 ::: {.alert .alert-warning}
202 Make sure to check the `deleted` property on each chat as this function might return information about deleted chats.
203 :::
204
205 **Parameters:**
206
207 1. `group_id: string`: Node part of the group's JID.
208
209 **Returns:**
210
211 ```lua
212 group_chats: {
213 {
214 id: string, -- muc_id (node part of the MUC JID)
215 jid: string,
216 name: string,
217 deleted: boolean,
218 }
219 }
220 | nil
221 ```
222
223 #### `emit_member_events(group_id)` {#emit_member_events}
224
225 Emits [`group-user-added`](#group-user-added) events for every member of a group.
226
227 **Parameters:**
228
229 1. `group_id: string`: Node part of the group's JID.
230
231 **Returns:** `true | false, error: string`
232
233 #### `groups()` {#groups}
234
235 Returns info about all groups (for every `group_id` key, the value is the equivalent of calling `get_info(group_id)`).
236
237 **Returns:**
238
239 ```lua
240 groups: {
241 <group_id>: {
242 name: string, 62 name: string,
243 muc_jid: string | nil 63 muc_jid: string | nil
244 } 64 }
245 } 65 | nil
246 ``` 66 ```
247 67
248 (Where `<group_id>` is a 68 - #### `set_info(group_id, info)` {#set_info}
249 69
250 ### Emitted events {#events} 70 Allows one to change a group's name. If `muc_jid` is specified, this function will also update the group chat's name.
251 71
252 #### `group-user-added` {#group-user-added} 72 **Parameters:**
253 73
254 Emitted on successful [`add_member`](#add_member) and on [`emit_member_events`](#emit_member_events). 74 1. `group_id: string`: Node part of the group's JID.
255 75 2. `group_info: { name: string, muc_jid: string | nil }`
256 Payload structure: 76
257 77 **Returns:** `true | nil, error: string`
258 ```lua 78
259 { 79 - #### `get_members(group_id)` {#get_members}
260 id: string, -- group_id (node part of the group's JID) 80
261 user: string, -- username (node part of the user's JID) 81 Retrieves the list of members in a given group.
262 host: string, -- <module.host> 82
263 group_info: { 83 **Parameters:**
264 name: string, 84
265 muc_jid: string | nil, 85 1. `group_id: string`: Node part of the group's JID.
266 mucs: {string} | nil, 86
267 }, 87 **Returns:** `group_members: {string}`
268 } 88
269 ``` 89 - #### `exists(group_id)` {#exists}
270 90
271 #### `group-user-removed` {#group-user-removed} 91 Returns whether or not a group exists.
272 92
273 Emitted on successful [`remove_member`](#remove_member). 93 **Parameters:**
274 94
275 Payload structure: 95 1. `group_id: string`: Node part of the group's JID.
276 96
277 ```lua 97 **Returns:** `group_exists: boolean`
278 { 98
279 id: string, -- group_id (node part of the group's JID) 99 - #### `get_user_groups(username)` {#get_user_groups}
280 user: string, -- username (node part of the user's JID) 100
281 host: string, -- <module.host> 101 Lists which groups a given user is a part of.
282 group_info: { 102
283 name: string, 103 **Parameters:**
284 muc_jid: string | nil, 104
285 mucs: {string} | nil, 105 1. `username: string`: Node part of the user's JID.
286 }, 106
287 } 107 **Returns:** `user_groups: {string}`
288 ``` 108
289 109 - #### `delete(group_id)` {#delete}
290 #### `group-chat-added` {#group-chat-added} 110
291 111 Deletes a given group and its associated group chats.
292 Emitted on successful [`add_group_chat`](#add_group_chat). 112
293 113 **Parameters:**
294 Payload structure: 114
295 115 1. `group_id: string`: Node part of the group's JID.
296 ```lua 116
297 { 117 **Returns:** `true | nil, error: string`
298 group_id: string, 118
299 group_info: { 119 - #### `add_member(group_id, username, delay_update)` {#add_member}
300 name: string, 120
301 mucs: {string}, 121 Adds a member to a given group, optionally delaying subscriptions until [`sync`](#sync) is called.
302 }, 122
123 ::: {.alert .alert-info}
124 This function emits a [`group-user-added`](#group-user-added) event on successful execution.
125 :::
126
127 **Parameters:**
128
129 1. `group_id: string`: Node part of the group's JID.
130 2. `delay_update: boolean | nil`: Do not update subscriptions until [`sync`](#sync) is called. Defaults to `false`.
131
132 **Returns:** `true | nil, error: string`
133
134 - #### `remove_member(group_id, username)` {#remove_member}
135
136 Removes a member from a given group.
137
138 ::: {.alert .alert-info}
139 This function emits a [`group-user-removed`](#group-user-removed) event on successful execution.
140 :::
141
142 **Parameters:**
143
144 1. `group_id: string`: Node part of the group's JID.
145 2. `username: string`: Node part of the user's JID.
146
147 **Returns:** `true | nil, error: string`
148
149 - #### `sync(group_id)` {#sync}
150
151 Updates group subscriptions (used to apply pending changes from [`add_member`](#add_member)).
152
153 **Parameters:**
154
155 1. `group_id: string`: Node part of the group's JID.
156
157 **Returns:** `nil`
158
159 - #### `add_group_chat(group_id, name)` {#add_group_chat}
160
161 Creates a new group chat for a given group.
162
163 ::: {.alert .alert-info}
164 Its JID will be `<`[`util.id.short`](https://prosody.im/doc/developers/util/id)`>@<`[`option:groups_muc_host`](#configuration)`>`.
165 :::
166
167 **Parameters:**
168
169 1. `group_id: string`: Node part of the group's JID.
170 2. `name: string`: Desired name of the group chat.
171
172 **Returns:**
173
174 ```lua
303 muc: { 175 muc: {
304 jid: string, 176 jid: string,
305 name: string, 177 name: string,
306 }, 178 }
307 } 179 | nil, error: string
308 ``` 180 ```
309 181
310 #### `group-chat-removed` {#group-chat-removed} 182 - #### `remove_group_chat(group_id, muc_id)` {#remove_group_chat}
311 183
312 Emitted on successful [`remove_group_chat`](#remove_group_chat). 184 Removes a group chat for a given group.
313 185
314 Payload structure: 186 ::: {.alert .alert-info}
315 187 This function emits a [`group-chat-removed`](#group-chat-removed) event on successful execution.
316 ```lua 188 :::
317 { 189
318 group_id: string, -- group_id (node part of the group's JID) 190 **Parameters:**
319 group_info: { 191
320 name: string, 192 1. `group_id: string`: Node part of the group's JID.
321 mucs: {string}, 193 2. `muc_id: string`: Node part of the MUC JID.
322 }, 194
323 muc: { 195 **Returns:** `true | nil, error: string`
324 id: string, -- muc_id (node part of the MUC JID) 196
325 jid: string, 197 - #### `get_group_chats(group_id)` {#get_group_chats}
326 }, 198
327 } 199 Lists group chats associated to a given group.
328 ``` 200
201 ::: {.alert .alert-warning}
202 Make sure to check the `deleted` property on each chat as this function might return information about deleted chats.
203 :::
204
205 **Parameters:**
206
207 1. `group_id: string`: Node part of the group's JID.
208
209 **Returns:**
210
211 ```lua
212 group_chats: {
213 {
214 id: string, -- muc_id (node part of the MUC JID)
215 jid: string,
216 name: string,
217 deleted: boolean,
218 }
219 }
220 | nil
221 ```
222
223 - #### `emit_member_events(group_id)` {#emit_member_events}
224
225 Emits [`group-user-added`](#group-user-added) events for every member of a group.
226
227 **Parameters:**
228
229 1. `group_id: string`: Node part of the group's JID.
230
231 **Returns:** `true | false, error: string`
232
233 - #### `groups()` {#groups}
234
235 Returns info about all groups (for every `group_id` key, the value is the equivalent of calling `get_info(group_id)`).
236
237 **Returns:**
238
239 ```lua
240 groups: {
241 <group_id>: {
242 name: string,
243 muc_jid: string | nil
244 }
245 }
246 ```
247
248 (Where `<group_id>` is a
249
250 ### Emitted events {#events}
251
252 - #### `group-user-added` {#group-user-added}
253
254 Emitted on successful [`add_member`](#add_member) and on [`emit_member_events`](#emit_member_events).
255
256 **Payload structure:**
257
258 ```lua
259 {
260 id: string, -- group_id (node part of the group's JID)
261 user: string, -- username (node part of the user's JID)
262 host: string, -- <module.host>
263 group_info: {
264 name: string,
265 muc_jid: string | nil,
266 mucs: {string} | nil,
267 },
268 }
269 ```
270
271 - #### `group-user-removed` {#group-user-removed}
272
273 Emitted on successful [`remove_member`](#remove_member).
274
275 **Payload structure:**
276
277 ```lua
278 {
279 id: string, -- group_id (node part of the group's JID)
280 user: string, -- username (node part of the user's JID)
281 host: string, -- <module.host>
282 group_info: {
283 name: string,
284 muc_jid: string | nil,
285 mucs: {string} | nil,
286 },
287 }
288 ```
289
290 - #### `group-chat-added` {#group-chat-added}
291
292 Emitted on successful [`add_group_chat`](#add_group_chat).
293
294 **Payload structure:**
295
296 ```lua
297 {
298 group_id: string,
299 group_info: {
300 name: string,
301 mucs: {string},
302 },
303 muc: {
304 jid: string,
305 name: string,
306 },
307 }
308 ```
309
310 - #### `group-chat-removed` {#group-chat-removed}
311
312 Emitted on successful [`remove_group_chat`](#remove_group_chat).
313
314 **Payload structure:**
315
316 ```lua
317 {
318 group_id: string, -- group_id (node part of the group's JID)
319 group_info: {
320 name: string,
321 mucs: {string},
322 },
323 muc: {
324 id: string, -- muc_id (node part of the MUC JID)
325 jid: string,
326 },
327 }
328 ```
329 329
330 [`mod_groups`]: https://prosody.im/doc/modules/mod_groups "mod_groups – Prosody IM" 330 [`mod_groups`]: https://prosody.im/doc/modules/mod_groups "mod_groups – Prosody IM"