view mod_muc_hats_api/README.markdown @ 4876:0f5f2d4475b9

mod_http_xep227: Add support for import via APIs rather than direct store manipulation In particular this transitions PEP nodes and data to be imported via mod_pep's APIs, fixing issues with importing at runtime while PEP data may already be live in RAM. Next obvious candidate for this approach is rosters, so clients get immediate roster pushes and other special handling (such as emitting subscribes to reach the desired subscription state).
author Matthew Wild <mwild1@gmail.com>
date Tue, 18 Jan 2022 17:01:18 +0000
parents e9e41e75c5a0
children
line wrap: on
line source

---
summary: API for managing MUC hats
---

# Introduction

This module provides an internal API (i.e. to other modules) to manage
'hats' for users in MUC rooms.

Hats (first defined in [XEP-0317], currently deferred) are additional identifiers
that can be attached to users in a group chat. For example in an educational
context, you may have a 'Teacher' hat that allows students to identify their
teachers.

Hats consist of a machine-readable unique identifier (a URI), and optionally
a human-readable label.

[XEP-0317] suggests a protocol for users to manage their own hats, but though the
API in this module allows for both user-managed and system-managed hats, there is
currently no protocol implemented for users to manage their own hats, which is
rarely desired in real-world implementations.

The rest of this documentation is designed for developers who use this module.

## Data model

### User

```
{
  "hats": {
    "urn:uuid:164c41a2-7461-4cff-bdae-3f93078a6607": {
      "active": false
    },
    "http://example.com/hats/foo": {
      "active": true,
      "required": true,
      "title": "Awesome"
    }
}
```

| Field | Type   | Description                                                  |
|-------|--------|--------------------------------------------------------------|
| hats  | object | An object where mapping hat ids (key) to attachments (value) |

Hat IDs must be a URI that uniquely identifies the hat.

### Attachment

```
{
  "active": true,
  "required": true,
  "title": "My Awesome Hat"
}
```

| Field    | Type    | Description                                                 |
|----------|---------|-------------------------------------------------------------|
| active   | boolean | If true, indicates the user is currently displaying the hat |
| required | boolean | If true, indicates the user is not able to remove the hat   |
| title    | string  | A human-readable display name or label for the hat          |

All fields are optional, omitted boolean values are equivalent to false.

## API

All methods return 'nil, err' on failure as standard throughout the Prosody codebase.

Example of using this module from another module:

```
local muc_hats = module:depends("muc_hats_api");

muc_hats.add_user_hat("user@localhost", "room@conference.localhost", "urn:uuid:164c41a2-7461-4cff-bdae-3f93078a6607", { active = true });
```

Note that the module only works when loaded on a MUC host, which generally means any
module that uses it must also be loaded on the MUC host that it is managing.

### add_user_hat

`add_user_hat(user_jid, room_jid, hat_id, attachment)`

Adds the identified hat to a user's... wardrobe? The user must already
have an affiliation with the room (i.e. member, admin or owner).

If `attachment` is omitted, it defaults to `{}`.

#### Error cases

item-not-found
: Supplied room JID was not found on the current host

item-not-found
: Supplied user JID was not affiliated with the room

### remove_user_hat

`remove_user_hat(user_jid, room_jid, hat_id)`

If the identified hat is currently available to the user, it is removed.

#### Error cases

item-not-found
: Supplied room JID was not found on the current host

item-not-found
: Supplied user JID was not affiliated with the room

### set_user_hats

`set_user_hats(user_jid, room_jid, hats)`

Ensures the listed hats are the hats available to a user, automatically
adding/removing as necessary.

The `hats` parameter should be an object mapping hat ids (keys) to attachment
objects (values).

#### Error cases

item-not-found
: Supplied room JID was not found on the current host

item-not-found
: Supplied user JID was not affiliated with the room