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 = SenderSnapshot.player(uuid, "Steve")
    recipient = Recipient(targetUuid, "Alex")
    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
事件系统	12 个事件，覆盖邮件发送/投递/阅读/领取/模板等流程	Events
Kether 动作	脚本中发送邮件和查询未读数	Kether Actions

包结构

kim.hhhhhy.assiah.api
├── AssiahAPI                // 核心 API 单例
├── dsl                      // DSL 扩展函数
├── service
│   ├── MailFacadeService    // 聚合门面接口
│   ├── MailPublicService    // 邮件核心操作
│   ├── DraftPublicService   // 草稿管理
│   ├── PreferencePublicService // 偏好与黑名单
│   ├── AdminPublicService   // 管理员操作
│   └── TemplatePublicService // 模板管理
├── request
│   ├── SendMailRequest      // 发送请求
│   ├── BroadcastMailRequest // 群发请求
│   ├── SaveDraftRequest     // 保存草稿请求
│   ├── SaveTemplateRequest  // 保存模板请求
│   ├── ApplyTemplateRequest // 应用模板请求
│   └── ...                  // 其他请求类
├── response
│   ├── SendResult           // 发送结果
│   ├── BroadcastResult      // 群发结果
│   ├── ClaimResult          // 领取结果
│   ├── DeleteResult         // 删除/归档/恢复结果
│   ├── ReadResult           // 阅读状态变更结果
│   ├── DraftResult          // 草稿操作结果
│   ├── TemplateResult       // 模板操作结果
│   └── ...                  // 其他结果类
├── mail
│   ├── SenderSnapshot       // 发送者快照
│   ├── Recipient            // 收件人
│   ├── MailAttachment       // 附件密封接口
│   ├── ItemAttachment       // 物品附件
│   ├── TextAttachment       // 文本附件
│   ├── KetherAttachment     // Kether 脚本附件
│   ├── CurrencyAttachment   // 货币附件
│   ├── SourceItemAttachment // 物品库物品附件
│   ├── MailSummary          // 邮件摘要
│   ├── Mail                 // 邮件详情
│   ├── MailDraft            // 草稿
│   ├── MailTemplate         // 模板
│   ├── MailThread           // 邮件会话
│   ├── MailboxPage          // 分页结果
│   └── ...                  // 其他数据类
├── event
│   ├── MailEvent            // 邮件事件基类
│   ├── MailSendEvent
│   ├── MailDeliveredEvent
│   ├── MailTemplateApplyEvent
│   ├── MailTemplateSaveEvent
│   ├── MailTemplateDeleteEvent
│   └── ...                  // 共 12 个事件
└── enums
    ├── MailFolder
    ├── AttachmentType
    ├── SourceType
    ├── RelationType
    └── ...

异步调用

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

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