Mercurial > prosody-modules

comparison mod_muc_hats_api/README.markdown @ 3947:1f90e333b1d8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_muc_hats_api: New API-only module for managing user hats in MUCs
author Matthew Wild <mwild1@gmail.com>
date Thu, 19 Mar 2020 14:39:14 +0000
parents
children e9e41e75c5a0
comparison
equal deleted inserted replaced
3946:2a5b42e4db07 3947:1f90e333b1d8
1 ---
2 summary: API for managing MUC hats
3 ---
4
5 # Introduction
6
7 This module provides an internal API (i.e. to other modules) to manage
8 'hats' for users in MUC rooms.
9
10 Hats (first defined in XEP-0317, currently deferred) are additional identifiers
11 that can be attached to users in a group chat. For example in an educational
12 context, you may have a 'Teacher' hat that allows students to identify their
13 teachers.
14
15 Hats consist of a machine-readable unique identifier (a URI), and optionally
16 a human-readable label.
17
18 XEP-0317 suggests a protocol for users to manage their own hats, but though the
19 API in this module allows for both user-managed and system-managed hats, there is
20 currently no protocol implemented for users to manage their own hats, which is
21 rarely desired in real-world implementations.
22
23 The rest of this documentation is designed for developers who use this module.
24
25 ## Data model
26
27 ### User
28
29 ```
30 {
31 "hats": {
32 "urn:uuid:164c41a2-7461-4cff-bdae-3f93078a6607": {
33 "active": false
34 },
35 "http://example.com/hats/foo": {
36 "active": true,
37 "required": true,
38 "title": "Awesome"
39 }
40 }
41 ```
42
43 | Field | Type | Description |
44 |-------|--------|--------------------------------------------------------------|
45 | hats | object | An object where mapping hat ids (key) to attachments (value) |
46
47 Hat IDs must be a URI that uniquely identifies the hat.
48
49 ### Attachment
50
51 ```
52 {
53 "active": true,
54 "required": true,
55 "title": "My Awesome Hat"
56 }
57 ```
58
59 | Field | Type | Description |
60 |----------|---------|-------------------------------------------------------------|
61 | active | boolean | If true, indicates the user is currently displaying the hat |
62 | required | boolean | If true, indicates the user is not able to remove the hat |
63 | title | string | A human-readable display name or label for the hat |
64
65 All fields are optional, omitted boolean values are equivalent to false.
66
67 ## API
68
69 All methods return 'nil, err' on failure as standard throughout the Prosody codebase.
70
71 Example of using this module from another module:
72
73 ```
74 local muc_hats = module:depends("muc_hats_api");
75
76 muc_hats.add_user_hat("user@localhost", "room@conference.localhost", "urn:uuid:164c41a2-7461-4cff-bdae-3f93078a6607", { active = true });
77 ```
78
79 Note that the module only works when loaded on a MUC host, which generally means any
80 module that uses it must also be loaded on the MUC host that it is managing.
81
82 ### add_user_hat
83
84 `add_user_hat(user_jid, room_jid, hat_id, attachment)`
85
86 Adds the identified hat to a user's... wardrobe? The user must already
87 have an affiliation with the room (i.e. member, admin or owner).
88
89 If `attachment` is omitted, it defaults to `{}`.
90
91 #### Error cases
92
93 item-not-found
94 : Supplied room JID was not found on the current host
95
96 item-not-found
97 : Supplied user JID was not affiliated with the room
98
99 ### remove_user_hat
100
101 `remove_user_hat(user_jid, room_jid, hat_id)`
102
103 If the identified hat is currently available to the user, it is removed.
104
105 #### Error cases
106
107 item-not-found
108 : Supplied room JID was not found on the current host
109
110 item-not-found
111 : Supplied user JID was not affiliated with the room
112
113 ### set_user_hats
114
115 `set_user_hats(user_jid, room_jid, hats)`
116
117 Ensures the listed hats are the hats available to a user, automatically
118 adding/removing as necessary.
119
120 The `hats` parameter should be an object mapping hat ids (keys) to attachment
121 objects (values).
122
123 #### Error cases
124
125 item-not-found
126 : Supplied room JID was not found on the current host
127
128 item-not-found
129 : Supplied user JID was not affiliated with the room