Mercurial > prosody-modules

comparison mod_groups_internal/README.md @ 6149:ce0579449dba

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_groups_internal: Rename README.markdown to README.md I had exported my last patch a long time ago, back when all READMEs were using .markdown.
author Rémi Bardon <remi@remibardon.name>
date Fri, 31 Jan 2025 01:49:01 +0100
parents
children 5250e4cb0b1a
comparison
equal deleted inserted replaced
6148:23e66cfc77d4 6149:ce0579449dba
1 ---
2 labels:
3 - 'Stage-Beta'
4 summary: Equivalent of mod_groups but without a configuration file
5 ---
6
7 ## Introduction
8
9 This module is functionally similar to [`mod_groups`], but it differs by working without a configuration file (allowing changes without a restart of the server) and by permanently adding users to each other's contact lists. To paraphrase [`mod_groups`]:
10
11 > `mod_groups_internal` was designed to allow administrators to create virtual groups of users that automatically see each other in their contact lists. There is no need for the user to authorise these contacts in their contact list - this is done automatically on the server.
12 >
13 > As an example, if you have a team of people working together on a project, you can create a group for that team. They will automatically be added to each others' contact lists, and the list can easily be modified on the server at any time to add and remove people.
14
15 ::: {.alert .alert-info}
16 On `user-deleted` events, `mod_groups_internal` will automatically remove the deleted user from every group they were part of.
17 :::
18
19 ## Setup
20
21 ```lua
22 modules_enabled = {
23 -- Other modules
24 "groups_internal"; -- Enable mod_groups_internal
25 }
26 ```
27
28 ## Configuration
29
30 ### `groups_muc_host` {#groups_muc_host}
31
32 | Option | Default | Notes |
33 | ------ | ------- | ----- |
34 | `groups_muc_host` | `groups.<module.host>` | Host where the group chats will be created. |
35
36 ## Usage
37
38 ### Exposed functions
39
40 #### `create(group_info, create_default_muc, group_id)` {#create}
41
42 Creates a new group, optionally creating a default MUC chat on [`groups_muc_host`](#groups_muc_host).
43
44 **Parameters:**
45
46 1. `group_info: { name: string }`
47 2. `create_default_muc: boolean | nil`: Whether or not to create the default MUC chat. Defaults to `false`.
48 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).
49
50 **Returns:** `group_id: string | nil, error: string`
51
52 #### `get_info(group_id)` {#get_info}
53
54 Retrieves information about a group.
55
56 **Parameters:**
57
58 1. `group_id: string`: Node part of the group's JID.
59
60 **Returns:**
61
62 ```lua
63 group_info: {
64 name: string,
65 muc_jid: string | nil
66 }
67 | nil
68 ```
69
70 #### `set_info(group_id, info)` {#set_info}
71
72 Allows one to change a group's name. If `muc_jid` is specified, this function will also update the group chat's name.
73
74 **Parameters:**
75
76 1. `group_id: string`: Node part of the group's JID.
77 2. `group_info: { name: string, muc_jid: string | nil }`
78
79 **Returns[^pseudo-lua]:** `true | nil, error: string`
80
81 #### `get_members(group_id)` {#get_members}
82
83 Retrieves the list of members in a given group.
84
85 **Parameters:**
86
87 1. `group_id: string`: Node part of the group's JID.
88
89 **Returns[^pseudo-lua]:** `group_members: [string]`
90
91 #### `exists(group_id)` {#exists}
92
93 Returns whether or not a group exists.
94
95 **Parameters:**
96
97 1. `group_id: string`: Node part of the group's JID.
98
99 **Returns:** `group_exists: boolean`
100
101 #### `get_user_groups(username)` {#get_user_groups}
102
103 Lists which groups a given user is a part of.
104
105 **Parameters:**
106
107 1. `username: string`: Node part of the user's JID.
108
109 **Returns[^pseudo-lua]:** `user_groups: [string]`
110
111 #### `delete(group_id)` {#delete}
112
113 Deletes a given group and its associated group chats.
114
115 **Parameters:**
116
117 1. `group_id: string`: Node part of the group's JID.
118
119 **Returns[^pseudo-lua]:** `true | nil, error: string`
120
121 #### `add_member(group_id, username, delay_update)` {#add_member}
122
123 Adds a member to a given group, optionally delaying subscriptions until [`sync`](#sync) is called.
124
125 ::: {.alert .alert-info}
126 This function emits a [`group-user-added`](#group-user-added) event on successful execution.
127 :::
128
129 **Parameters:**
130
131 1. `group_id: string`: Node part of the group's JID.
132 2. `delay_update: boolean | nil`: Do not update subscriptions until [`sync`](#sync) is called. Defaults to `false`.
133
134 **Returns:** `true | nil, error: string`
135
136 #### `remove_member(group_id, username)` {#remove_member}
137
138 Removes a member from a given group.
139
140 ::: {.alert .alert-info}
141 This function emits a [`group-user-removed`](#group-user-removed) event on successful execution.
142 :::
143
144 **Parameters:**
145
146 1. `group_id: string`: Node part of the group's JID.
147 2. `username: string`: Node part of the user's JID.
148
149 **Returns:** `true | nil, error: string`
150
151 #### `sync(group_id)` {#sync}
152
153 Updates group subscriptions (used to apply pending changes from [`add_member`](#add_member)).
154
155 **Parameters:**
156
157 1. `group_id: string`: Node part of the group's JID.
158
159 **Returns:** `nil`
160
161 #### `add_group_chat(group_id, name)` {#add_group_chat}
162
163 Creates a new group chat for a given group.
164
165 ::: {.alert .alert-info}
166 Its JID will be `<`[`util.id.short`](https://prosody.im/doc/developers/util/id)`>@<`[`option:groups_muc_host`](#groups_muc_host)`>`.
167 :::
168
169 **Parameters:**
170
171 1. `group_id: string`: Node part of the group's JID.
172 2. `name: string`: Desired name of the group chat.
173
174 **Returns[^pseudo-lua]:**
175
176 ```lua
177 muc: {
178 jid: string,
179 name: string,
180 }
181 | nil, error: string
182 ```
183
184 #### `remove_group_chat(group_id, muc_id)` {#remove_group_chat}
185
186 Removes a group chat for a given group.
187
188 ::: {.alert .alert-info}
189 This function emits a [`group-chat-removed`](#group-chat-removed) event on successful execution.
190 :::
191
192 **Parameters:**
193
194 1. `group_id: string`: Node part of the group's JID.
195 2. `muc_id: string`: Node part of the MUC JID.
196
197 **Returns[^pseudo-lua]:** `true | nil, error: string`
198
199 #### `get_group_chats(group_id)` {#get_group_chats}
200
201 Lists group chats associated to a given group.
202
203 ::: {.alert .alert-warning}
204 Make sure to check the `deleted` property on each chat as this function might return information about deleted chats.
205 :::
206
207 **Parameters:**
208
209 1. `group_id: string`: Node part of the group's JID.
210
211 **Returns[^pseudo-lua]:**
212
213 ```lua
214 group_chats: [
215 {
216 id: string, -- muc_id (node part of the MUC JID)
217 jid: string,
218 name: string,
219 deleted = boolean,
220 }
221 ]
222 | nil
223 ```
224
225 #### `emit_member_events(group_id)` {#emit_member_events}
226
227 Emits [`group-user-added`](#group-user-added) events for every member of a group.
228
229 **Parameters:**
230
231 1. `group_id: string`: Node part of the group's JID.
232
233 **Returns[^pseudo-lua]:** `true | false, error: string`
234
235 #### `groups()` {#groups}
236
237 Returns info about all groups (for every `group_id` key, the value is the equivalent of calling `get_info(group_id)`).
238
239 **Returns[^pseudo-lua]:**
240
241 ```lua
242 groups: {
243 [<group_id>]: {
244 name: string,
245 muc_jid: string | nil
246 }
247 }
248 ```
249
250 (Where `<group_id>` is a
251
252 ### Emitted events {#events}
253
254 #### `group-user-added` {#group-user-added}
255
256 Emitted on successful [`add_member`](#add_member) and on [`emit_member_events`](#emit_member_events).
257
258 Payload structure:
259
260 ```lua
261 {
262 id: string, -- group_id (node part of the group's JID)
263 user: string, -- username (node part of the user's JID)
264 host: string, -- <module.host>
265 group_info: {
266 name: string,
267 muc_jid: string | nil,
268 mucs: [string] | nil,
269 },
270 }
271 ```
272
273 #### `group-user-removed` {#group-user-removed}
274
275 Emitted on successful [`remove_member`](#remove_member).
276
277 Payload structure:
278
279 ```lua
280 {
281 id: string, -- group_id (node part of the group's JID)
282 user: string, -- username (node part of the user's JID)
283 host: string, -- <module.host>
284 group_info: {
285 name: string,
286 muc_jid: string | nil,
287 mucs: [string] | nil,
288 },
289 }
290 ```
291
292 #### `group-chat-added` {#group-chat-added}
293
294 Emitted on successful [`add_group_chat`](#add_group_chat).
295
296 Payload structure:
297
298 ```lua
299 {
300 group_id: string,
301 group_info: {
302 name: string,
303 mucs: [string],
304 },
305 muc: {
306 jid: string,
307 name: string,
308 },
309 }
310 ```
311
312 #### `group-chat-removed` {#group-chat-removed}
313
314 Emitted on successful [`remove_group_chat`](#remove_group_chat).
315
316 Payload structure:
317
318 ```lua
319 {
320 group_id: string, -- group_id (node part of the group's JID)
321 group_info: {
322 name: string,
323 mucs: [string],
324 },
325 muc: {
326 id: string, -- muc_id (node part of the MUC JID)
327 jid: string,
328 },
329 }
330 ```
331
332 [^pseudo-lua]: As "pseudo-Lua" code. `[…]` represents a list and `[…]` as a map key means `0..n` times the key (it's not just one element).
333
334 [`mod_groups`]: https://prosody.im/doc/modules/mod_groups "mod_groups – Prosody IM"