attachment stub / docs

README.md

@@ -7,6 +7,10 @@ This is a fork of cheapies mail mod
 
 It adds a mail-system that allows players to send each other messages in-game and via webmail (optional)
 
+# Docs
+
+* [Api](./api.md)
+
 # Screenshots
 
 Ingame mail

api.lua

@@ -1,3 +1,4 @@
+-- see: mail.md
 
 mail.registered_on_receives = {}
 function mail.register_on_receive(func)
@@ -7,36 +8,35 @@ end
 mail.receive_mail_message = "You have a new message from %s! Subject: %s\nTo view it, type /mail"
 mail.read_later_message = "You can read your messages later by using the /mail command"
 
-function mail.send(src, dst, subject, body)
+function mail.send(m) -- see: "Mail format"
-	minetest.log("action", "[mail] '" .. src .. "' sends mail to '" .. dst ..
+	minetest.log("action", "[mail] '" .. m.src .. "' sends mail to '" .. m.dst ..
-		"' with subject '" .. subject .. "' and body: '" .. body .. "'")
+		"' with subject '" .. m.subject .. "' and body: '" .. m.body .. "'")
 
-	local messages = mail.getMessages(dst)
+	local messages = mail.getMessages(m.dst)
 
 	table.insert(messages, 1, {
 		unread  = true,
-		sender  = src,
+		sender  = m.src,
-		subject = subject,
+		subject = m.subject,
-		body    = body,
+		body    = m.body,
 		time    = os.time(),
 	})
-	mail.setMessages(dst, messages)
+	mail.setMessages(m.dst, messages)
 
 	for _, player in ipairs(minetest.get_connected_players()) do
 		local name = player:get_player_name()
-		if name == dst then
+		if name == m.dst then
-			if subject == "" then subject = "(No subject)" end
+			if m.subject == "" then m.subject = "(No subject)" end
-			if string.len(subject) > 30 then
+			if string.len(m.subject) > 30 then
-				subject = string.sub(subject,1,27) .. "..."
+				m.subject = string.sub(m.subject,1,27) .. "..."
 			end
-			minetest.chat_send_player(dst,
+			minetest.chat_send_player(m.dst,
-					string.format(mail.receive_mail_message, src, subject))
+					string.format(m.receive_mail_message, m.src, m.subject))
 		end
 	end
-	mail.save()
 
 	for i=1, #mail.registered_on_receives do
-		if mail.registered_on_receives[i](src, dst, subject, body) then
+		if mail.registered_on_receives[i](m) then
 			break
 		end
 	end

api.md

@@ -0,0 +1,43 @@
+
+# Mail format
+The mail format in the api hooks
+
+```lua
+mail = {
+	src = "source name",
+	dst = "destination name",
+	subject = "subject line",
+	body = "mail body",
+	-- 8 attachments max
+	attachments = {"default:stone 99", "default:gold_ingot 99"}
+}
+```
+
+# Hooks
+On-receive mail hook:
+
+```lua
+mail.register_on_receive(function(m)
+	-- "m" is an object in the form: "Mail format"
+end)
+```
+
+# internal mail format (on-disk)
+The mail format on-disk
+
+> (worldfolder)/mails/(playername).json
+
+```json
+[{
+	"unread": true,
+	"sender": "sender name",
+	"subject": "subject name",
+	"body": "main\nmultiline\nbody",
+	"time": 1551258349,
+	"attachments": [
+		"default:stone 99",
+		"default:gold_ingot 99"
+	]
+}]
+
+```

attachment.lua

@@ -0,0 +1,25 @@
+
+local invmap = {}
+
+
+mail.getAttachmentInventory = function(playername)
+	return invmap[playername]
+end
+
+mail.getAttachmentInventoryName = function(playername)
+	return "mail:" .. name
+end
+
+
+minetest.register_on_joinplayer(function(player)
+	local name = player:get_player_name()
+	local inv = minetest.create_detached_inventory(mail.getAttachmentInventoryName(name), {})
+
+	invmap[name] = inv
+end)
+
+minetest.register_on_leaveplayer(function(player)
+	local name = player:get_player_name()
+	invmap[name] = nil
+	minetest.remove_detached_inventory(mail.getAttachmentInventoryName(name))
+end)

gui.lua

@@ -214,7 +214,12 @@ function mail.handle_receivefields(player, formname, fields)
 		return true
 	elseif formname == "mail:compose" then
 		if fields.send then
-			mail.send(player:get_player_name(), fields.to, fields.subject, fields.body)
+			mail.send({
+				src = player:get_player_name(),
+				dst = fields.to,
+				subject = fields.subject,
+				body = fields.body
+			})
 		end
 		minetest.after(0.5, function()
 			mail.show_inbox(player:get_player_name())

init.lua

@@ -1,11 +1,25 @@
 mail = {
-	maildir = minetest.get_worldpath().."/mails"
+	-- mail directory
+	maildir = minetest.get_worldpath().."/mails",
+
+	-- allow item/node attachments
+	allow_attachments = minetest.settings:get("mail.allow_attachments") == "true",
+
+	webmail = {
+		-- disallow banned players in the webmail interface
+		disallow_banned_players = minetest.settings:get("webmail.disallow_banned_players") == "true",
+
+		-- url and key to the webmail server
+		url = minetest.settings:get("webmail.url"),
+		key = minetest.settings:get("webmail.key")
+	}
 }
 
 
 local MP = minetest.get_modpath(minetest.get_current_modname())
 dofile(MP .. "/chatcommands.lua")
 dofile(MP .. "/migrate.lua")
+dofile(MP .. "/attachment.lua")
 dofile(MP .. "/hud.lua")
 dofile(MP .. "/storage.lua")
 dofile(MP .. "/api.lua")
@@ -22,8 +36,8 @@ webmail.key = myserverkey
 local http = minetest.request_http_api()
 
 if http then
-	local webmail_url = minetest.settings:get("webmail.url")
+	local webmail_url = mail.webmail.url
-	local webmail_key = minetest.settings:get("webmail.key")
+	local webmail_key = mail.webmail.key
 
 	if not webmail_url then error("webmail.url is not defined") end
 	if not webmail_key then error("webmail.key is not defined") end

webmail.lua

@@ -1,5 +1,4 @@
 -- false per default
-local disallow_banned_players = minetest.settings:get("webmail.disallow_banned_players") == "true"
 local has_xban2_mod = minetest.get_modpath("xban2")
 
 local MP = minetest.get_modpath(minetest.get_current_modname())
@@ -15,7 +14,7 @@ local function auth_handler(auth)
 	local banned = false
 	local message = ""
 
-	if disallow_banned_players and has_xban2_mod then
+	if mail.webmail.disallow_banned_players and has_xban2_mod then
 		-- check xban db
 		local xbanentry = xban.find_entry(auth.name)
 		if xbanentry and xbanentry.banned then
@@ -45,7 +44,7 @@ end
 local function send_handler(sendmail)
 	-- send mail from webclient
 	minetest.log("action", "[webmail] sending mail from webclient: " .. sendmail.src .. " -> " .. sendmail.dst)
-	mail.send(sendmail.src, sendmail.dst, sendmail.subject, sendmail.body)
+	mail.send(sendmail)
 end
 
 -- get player messages request from webmail
@@ -85,15 +84,10 @@ local function mark_mail_unread_handler(playername, index)
 	mail.setMessages(playername, messages)
 end
 
-function mail.webmail_send_hook(src,dst,subject,body)
+function mail.webmail_send_hook(m)
 	channel.send({
 		type = "new-message",
-		data = {
+		data = m
-			src=src,
-			dst=dst,
-			subject=subject,
-			body=body
-		}
 	})
 end
 mail.register_on_receive(mail.webmail_send_hook)