开发者 API

Assiah 提供完整的 API 供其他插件集成邮箱功能。所有 API 通过 AssiahAPI 单例对象调用，返回 CompletableFuture 异步结果。

面向开发者

本页面面向插件开发者。如果你是服主，可以跳过此页。

引入依赖

// build.gradle.kts
repositories {
    // Assiah 发布仓库（或本地 libs 目录）
}

dependencies {
    compileOnly(fileTree("libs") { include("Assiah-*.jar") })
}

核心入口

import kim.hhhhhy.assiah.api.AssiahAPI

AssiahAPI 是所有公开 API 的唯一入口。插件启动后即可调用，无需手动初始化。

发送邮件

基础方式（构建 Request）

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.mail.Recipient
import kim.hhhhhy.assiah.api.mail.SenderSnapshot
import kim.hhhhhy.assiah.api.request.SendMailRequest

val request = SendMailRequest(
    sender = SenderSnapshot.player(uuid, "Steve"),
    recipient = Recipient(targetUuid, "Alex"),
    title = "你好",
    body = "这是一封测试邮件"
)

AssiahAPI.sendMail(request).thenAccept { result ->
    if (result.success) {
        println("邮件发送成功，ID: ${result.mailId}")
    } else {
        println("发送失败: ${result.failure?.code}")
    }
}

DSL 参数展开

import kim.hhhhhy.assiah.api.dsl.sendMail

AssiahAPI.sendMail(
    sender = SenderSnapshot.player(uuid, "Steve"),
    recipient = Recipient(targetUuid, "Alex"),
    title = "你好",
    body = "这是一封测试邮件"
)

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.sendMail

AssiahAPI.sendMail {
    sender = SenderSnapshot.player(uuid, "Steve")
    recipient = Recipient(targetUuid, "Alex")
    title = "你好"
    body = "这是一封测试邮件"
    attachment(ItemAttachment(itemStack))
    expireAt = System.currentTimeMillis() + 86400000L  // 24 小时后过期
}

发送系统邮件

系统邮件的发送者类型为系统，可能绕过部分用户偏好限制。

DSL 参数展开

import kim.hhhhhy.assiah.api.dsl.sendSystemMail

// 通过 Recipient 对象
AssiahAPI.sendSystemMail(
    recipient = Recipient(targetUuid, "Alex"),
    title = "系统通知",
    body = "你的背包已满"
)

// 通过 UUID + 玩家名（最简化）
AssiahAPI.sendSystemMail(
    recipientUuid = targetUuid,
    recipientName = "Alex",
    title = "系统通知",
    body = "你的背包已满"
)

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.sendSystemMail

AssiahAPI.sendSystemMail {
    recipient = Recipient(targetUuid, "Alex")
    title = "系统通知"
    body = "你的背包已满"
    attachment(ItemAttachment(itemStack))
}

群发邮件

向多个收件人同时发送相同内容的邮件。每个收件人独立执行发送操作，单个失败不影响其他收件人。

基础方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.request.BroadcastMailRequest

val request = BroadcastMailRequest(
    sender = SenderSnapshot.system(),
    recipients = listOf(
        Recipient(uuid1, "Steve"),
        Recipient(uuid2, "Alex")
    ),
    title = "服务器公告",
    body = "维护通知：今晚 22:00 停服维护"
)

AssiahAPI.broadcastMail(request).thenAccept { result ->
    println("群发完成: 成功 ${result.successCount}, 失败 ${result.failureCount}")
}

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.broadcastMail

AssiahAPI.broadcastMail {
    sender = SenderSnapshot.system()
    recipients(onlineRecipients)
    title = "服务器公告"
    body = "维护通知：今晚 22:00 停服维护"
    attachment(TextAttachment("详细说明"))
}

BroadcastResult

字段	类型	说明
total	Int	收件人总数
successCount	Int	发送成功数量
failureCount	Int	发送失败数量
failures	List<BroadcastFailure>	失败详情列表

每个 BroadcastFailure 包含 recipientName（收件人名称）和 failure（失败原因）。

查询邮箱

基础方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.request.MailboxQuery

val query = MailboxQuery(
    ownerId = playerUuid,
    page = 1,
    pageSize = 21,
    filter = MailboxFilter(folder = MailFolder.INBOX)
)

AssiahAPI.queryMailbox(query).thenAccept { page ->
    println("共 ${page.total} 封邮件，当前页 ${page.items.size} 封")
}

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.queryMailbox

AssiahAPI.queryMailbox(playerUuid) {
    page = 1
    pageSize = 21
    folder = MailFolder.INBOX
    unreadOnly = true
    keywords = "公告"
}

其他 API

方法	说明	返回类型
readMail(ownerId, mailId)	标记邮件为已读并返回完整内容	CompletableFuture<ReadResult>
claimAttachments(ownerId, mailId)	领取邮件附件	CompletableFuture<ClaimResult>
deleteMail(ownerId, mailId)	删除邮件（移入回收站）	CompletableFuture<DeleteResult>
moveMail(ownerId, mailId, folder)	移动邮件到指定文件夹	CompletableFuture<MoveResult>
replyMail(request)	回复邮件	CompletableFuture<SendResult>
forwardMail(request)	转发邮件	CompletableFuture<SendResult>
getUnreadCount(ownerId)	获取未读邮件数量	CompletableFuture<Long>
getMailThread(ownerId, mailId)	获取邮件会话线程	CompletableFuture<MailThread>
updatePreference(request)	更新收件偏好	CompletableFuture<PreferenceResult>
blockPlayer(request)	添加/移除黑名单	CompletableFuture<BlockResult>
batchOperation(request)	批量操作（删除/归档/标记已读等）	CompletableFuture<BatchOperationResult>

附件类型

在发送邮件时，可以通过 attachments 参数添加附件：

import kim.hhhhhy.assiah.api.mail.ItemAttachment
import kim.hhhhhy.assiah.api.mail.TextAttachment
import kim.hhhhhy.assiah.api.mail.KetherAttachment
import kim.hhhhhy.assiah.api.mail.CurrencyAttachment

// 物品附件
val item = ItemAttachment(itemStack, displayName = "钻石剑")

// 文本附件
val text = TextAttachment("这是一段说明文字")

// Kether 脚本附件（仅系统邮件/管理员可用）
val kether = KetherAttachment("command \"give {player} diamond 1\" as console")

// 货币附件
val currency = CurrencyAttachment(
    currencyKey = "vault",      // 对应 currency.yml 中的键名
    amount = 1000.0,
    displayName = "1000 金币"
)

Kether 自定义动作

Assiah 注册了 3 个 Kether 动作，可在其他插件的 Kether 脚本中使用：

动作	参数	说明	返回值
mail-send	<收件人> <标题> <正文>	发送系统邮件	Boolean
mail-unread	[玩家]	获取未读邮件数量	Long
mail-has-unread	[玩家]	是否有未读邮件	Boolean

注意事项

• 所有 API 返回 CompletableFuture，在异步线程执行。如需在主线程处理结果，请使用 Bukkit 调度器回调
• 插件未完成初始化时调用 API 会返回 API_NOT_READY 错误
• 群发邮件默认跳过发送者速率限制，但收件人数量受 maxBatchSendSize 配置限制
• 货币附件和 Kether 附件在 API 层发送时不会自动扣款/校验，需调用方自行处理