Assiah API 概述

Assiah 是一个全功能邮箱系统，提供完整的异步 API。所有方法返回 CompletableFuture，天然支持异步调用。

获取 API 实例

AssiahAPI 是一个 Kotlin object（单例），直接引用即可：

import kim.hhhhhy.assiah.api.AssiahAPI

// 直接使用
AssiahAPI.sendMail(request)

DSL 扩展

Assiah 在 kim.hhhhhy.assiah.api.dsl 包下提供了 Kotlin DSL 扩展，简化 API 调用：

import kim.hhhhhy.assiah.api.dsl.*

// DSL 风格发送邮件
AssiahAPI.sendMail {
    sender = senderUUID
    receiver = receiverUUID
    title = "测试邮件"
    body = "这是一封测试邮件"
}

依赖配置

从售后群获取 Assiah-api.jar 文件，放入项目的 libs/ 目录：

Gradle (Kotlin DSL)

dependencies {
    compileOnly(files("libs/Assiah-api.jar"))
}

Maven

<dependency>
    <groupId>kim.hhhhhy</groupId>
    <artifactId>assiah-api</artifactId>
    <version>最新版本</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/Assiah-api.jar</systemPath>
</dependency>

plugin.yml

depend: [Assiah]
# 或软依赖
softdepend: [Assiah]

API 模块一览

模块	说明	文档
发送 API	发送玩家邮件、系统邮件、群发邮件	Send API
查询 API	邮箱查询、邮件操作、偏好设置、管理员功能	Query API
草稿 API	草稿的保存、查询、删除、发送	Draft API
事件系统	9 个事件，覆盖邮件发送/投递/阅读/领取等流程	Events
Kether 动作	脚本中发送邮件和查询未读数	Kether Actions

包结构

kim.hhhhhy.assiah.api
├── AssiahAPI                // 核心 API 单例
├── dsl                      // DSL 扩展函数
├── request
│   ├── SendMailRequest      // 发送请求
│   └── BroadcastMailRequest // 群发请求
├── result
│   ├── SendResult           // 发送结果
│   └── BroadcastResult      // 群发结果
├── attachment
│   ├── ItemAttachment       // 物品附件
│   ├── TextAttachment       // 文本附件
│   ├── KetherAttachment     // Kether 脚本附件
│   └── CurrencyAttachment   // 货币附件
├── event
│   ├── MailSendEvent
│   ├── MailDeliveredEvent
│   └── ...                  // 共 9 个事件
└── enums
    ├── MailFolder
    ├── AttachmentType
    └── ...

异步调用

所有 API 方法返回 CompletableFuture，不会阻塞主线程：

AssiahAPI.getUnreadCount(playerUUID).thenAccept { count ->
    // 回调在异步线程执行
    // 如需操作 Bukkit API，请切回主线程
    Bukkit.getScheduler().runTask(plugin) { _ ->
        player.sendMessage("你有 $count 封未读邮件")
    }
}