--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_muc_hats_adhoc/README.markdown	Thu Mar 19 14:51:44 2020 +0000
@@ -0,0 +1,37 @@
+---
+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.
+
+This module provides ad-hoc commands for MUC service admins to add/remove hats
+to/from users in MUC rooms. It depends (automatically) on mod_muc_hats_api.
+
+## Configuration
+
+```
+Component "conference.example.com" "muc"
+  modules_enabled = { "muc_hats_adhoc" }
+```
+
+## Usage
+
+To successfully use the module you will need to use an XMPP client that is
+capable of sending commands to a specific host (e.g. via the service discovery
+browser in Gajim, Psi/Psi+ and other clients), and you'll find the commands
+on the MUC host.
+
+Also note that the display of hats in clients is currently non-existent, but
+will hopefully improve after XEP-0317 is resurrected or replaced.
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_muc_hats_adhoc/mod_muc_hats_adhoc.lua	Thu Mar 19 14:51:44 2020 +0000
@@ -0,0 +1,71 @@
+module:depends("adhoc");
+local adhoc_new = module:require("adhoc").new;
+local hats_api = module:depends("muc_hats_api");
+
+local dataforms_new = require "util.dataforms".new;
+local adhoc_simple = require "util.adhoc".new_simple_form;
+
+local function generate_error_message(errors)
+	local errmsg = {};
+	for name, err in pairs(errors) do
+		errmsg[#errmsg + 1] = name .. ": " .. err;
+	end
+	return { status = "completed", error = { message = table.concat(errmsg, "\n") } };
+end
+
+local add_hat_form_layout = dataforms_new {
+	title = "Add a hat";
+	instructions = "Assign a hat to a room member";
+
+	{ name = "user",  type = "jid-single",  label = "User JID", required = true };
+	{ name = "room",  type = "jid-single",  label = "Room JID", required = true };
+	{ name = "title", type = "text-single", label = "Hat title" };
+	{ name = "uri",   type = "text-single", label = "Hat URI",  required = true };
+};
+
+local add_hat_handler = adhoc_simple(add_hat_form_layout, function (fields, errs)
+	if errs then
+		return generate_error_message(errs);
+	end
+
+	local ok, err_cond, err_text = hats_api.add_user_hat(fields.user, fields.room, fields.uri, {
+		active = true;
+		required = true;
+		title = fields.title;
+	});
+
+	return {
+		status = "completed";
+		info = ok and "The hat has been added successfully" or ("There was an error adding the hat: "..(err_text or err_cond));
+	};
+
+end);
+
+local remove_hat_form_layout = dataforms_new {
+	title = "Remove a hat";
+	instructions = "Remove a hat from a room member";
+
+	{ name = "user",  type = "jid-single",  label = "User JID", required = true };
+	{ name = "room",  type = "jid-single",  label = "Room JID", required = true };
+	{ name = "uri",   type = "text-single", label = "Hat URI",  required = true };
+};
+
+local remove_hat_handler = adhoc_simple(remove_hat_form_layout, function (fields, errs)
+	if errs then
+		return generate_error_message(errs);
+	end
+
+	local ok, err_cond, err_text = hats_api.remove_user_hat(fields.user, fields.room, fields.uri);
+
+	return {
+		status = "completed";
+		info = ok and "The hat has been removed successfully" or ("There was an error removing the hat: "..(err_text or err_cond));
+	};
+
+end);
+
+local add_hat_desc = adhoc_new("Add hat to a user", "http://prosody.im/protocol/hats#add", add_hat_handler, "admin");
+local remove_hat_desc = adhoc_new("Remove hat from a user", "http://prosody.im/protocol/hats#remove", remove_hat_handler, "admin");
+
+module:provides("adhoc", add_hat_desc);
+module:provides("adhoc", remove_hat_desc);