yeow-api 0.2.114 → 0.2.115

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.2.114",
+    "version": "0.2.115",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/command.ts

@@ -1,11 +1,16 @@
 import { call } from './task.js';
 import type { TaskOptions } from './task.js';
+import { Player } from './player.js';
+import type { Permission } from './permission.js';
+import type { PermissionOptions } from './permission.js';
+import { permissionPayload } from './permission.js';
 
-export interface CommandSender {
-  readonly name: string;
-  readonly uuid: string;
-  readonly isPlayer: boolean;
-  sendMessage(msg: string): void;
+/** 命令发送者：玩家为真正的 `Player` 对象（异步 `sendMessage` 等全部方法）；控制台为字符串 `'CONSOLE'`。 */
+export type CommandSender = Player | 'CONSOLE';
+
+/** 判断发送者是否为玩家（非 'CONSOLE' 即玩家）。 */
+export function isPlayer(sender: CommandSender): sender is Player {
+  return sender !== 'CONSOLE';
 }
 
 export interface CommandPayload {
@@ -23,7 +28,12 @@ export interface ManualCompleter {
 export interface CommandOptions {
   description?: string;
   usage?: string;
-  permission?: string;
+  /**
+   * 权限节点：字符串（兼容）或权限节点对象 `{ node, default }`（或 `registerPermission` 返回值）。
+   * 节点注册进 Bukkit 权限系统（权限插件/ permissions.yml 可管理）；**执行时检查**——
+   * `permissionCheck` 事件结果优先，无处理时回退 Bukkit `hasPermission`。未声明则所有人可执行。
+   */
+  permission?: string | Permission | PermissionOptions;
   aliases?: string[];
   executor: (payload: CommandPayload) => void;
   completer?: CompleterFn | ManualCompleter;
@@ -34,21 +44,17 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
   const completer = options.completer;
   const pluginName = __plugin?.name || 'unknown';
 
-  function decorateSender(sender: CommandSender): CommandSender {
-    if (sender?.uuid && sender.isPlayer) {
-      (sender as any).sendMessage = (msg: string) => {
-        call('player.sendMessage', { uuid: sender.uuid, message: msg }, taskOptions);
-      };
-    } else {
-      (sender as any).sendMessage = (msg: string) => {
-        $send('log', { level: 'INFO', message: msg });
-      };
+  /** 原始 sender（{name, uuid, isPlayer}）→ 真正的 Player 或 'CONSOLE'。 */
+  function adaptSender(raw: any): CommandSender {
+    if (raw?.isPlayer) {
+      const p = Player.getSync(raw.uuid);
+      if (p) return p;
     }
-    return sender;
+    return 'CONSOLE';
   }
 
   const cbId = _registerCallback((payload: CommandPayload) => {
-    (payload as any).sender = decorateSender(payload.sender);
+    (payload as any).sender = adaptSender(payload.sender);
     executor(payload);
   }, { persistent: true });
 
@@ -65,7 +71,7 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
 
     compCbId = _registerCallback((data: any) => {
       try {
-        const sender = decorateSender(data.sender);
+        const sender = adaptSender(data.sender);
         if (manualRelease) {
           const complete = (result: string[]) => {
             $send('task', {
@@ -108,7 +114,7 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
     completerCbId: compCbId,
     description: options.description,
     usage: options.usage,
-    permission: options.permission,
+    permission: options.permission ? permissionPayload(options.permission) : undefined,
     aliases: options.aliases,
   }, taskOptions);
 }

package/src/core.ts

@@ -27,6 +27,7 @@ export type {
     BlockBreakEvent, BlockPlaceEvent, BlockFadeEvent, BlockGrowEvent, BlockSpreadEvent, BlockExplodeEvent,
     InventoryOpenEvent, InventoryCloseEvent, InventoryClickEvent,
     ServerPingEvent, ServerCommandEvent,
+    PermissionCheckEvent,
     PlayerResourcePackStatusEvent,
 } from './event.js';
 export { onInit, onLoad, onUnload } from './lifecycle.js';
@@ -94,5 +95,7 @@ export { log, Logger } from './log.js';
 export type { Message } from './message.js';
 export { getEnv } from './env.js';
 export type { EnvInfo } from './env.js';
+export { registerPermission } from './permission.js';
+export type { Permission, PermissionOptions, PermissionDefault } from './permission.js';
 export { createWorker, Worker, onMessage, postMessage } from './worker.js';
 export type { WorkerOptions } from './worker.js';

package/src/event.ts

@@ -254,6 +254,27 @@ export interface ServerCommandEvent {
   sender: string;
   cancelled?: boolean;
 }
+
+/**
+ * Yeow 生态权限检查（仅 `player.hasPermission` 任务与 Yeow 插件注册命令的执行检查触发；
+ * 其他 Java 插件的 hasPermission / 命令不会触发）。
+ *
+ * handler 返回 `{ allowed: <boolean> }` 决定结果；**不返回视为未处理**（回退 Bukkit hasPermission）。
+ * 多个 handler 都返回且结果冲突时，以**最后一个返回的为准**（不保证执行顺序）。
+ *
+ * ⚠ 普通插件不建议监听（每次权限检查都触发，影响性能）——专为 Yeow 生态权限管理插件设计。
+ * ⚠ handler 中调用 `hasPermission` 会再次触发本检查——**可能导致无限循环**，请避免。
+ */
+export interface PermissionCheckEvent {
+  /** 检查对象：玩家 UUID 或 "CONSOLE"。 */
+  target: string;
+  /** 权限节点（如 "myplugin.home"）。 */
+  node: string;
+  /** 权限对象（含节点默认值，`registerPermission` 或命令声明的权限）。 */
+  permission: { node: string; default?: string };
+  /** handler 返回 `{ allowed }` 决定结果。 */
+  allowed?: boolean;
+}
 export interface InventoryClickEvent {
   player: Player;
   slot: number;
@@ -316,6 +337,7 @@ type EventMap = {
   inventoryClose: InventoryCloseEvent;
   serverPing: ServerPingEvent;
   serverCommand: ServerCommandEvent;
+  permissionCheck: PermissionCheckEvent;
   playerTeleport: PlayerTeleportEvent;
   playerItemConsume: PlayerItemConsumeEvent;
   inventoryClick: InventoryClickEvent;

package/src/permission.ts

@@ -0,0 +1,46 @@
+import { call } from './task.js';
+import type { TaskOptions } from './task.js';
+
+/** 权限节点默认值：'all' = 所有人默认拥有；'op' = 仅 op（默认）；'none' = 需授权。 */
+export type PermissionDefault = 'all' | 'op' | 'none';
+
+export interface PermissionOptions {
+  /** 权限节点（如 `myplugin.home`）。 */
+  node: string;
+  /** 默认值（默认 'op'）。 */
+  default?: PermissionDefault;
+}
+
+/** 权限节点对象（注册后返回）。 */
+export interface Permission {
+  node: string;
+  default: PermissionDefault;
+}
+
+let _registered: Record<string, Permission> = {};
+
+/**
+ * 注册权限节点（幂等）：节点注册进 Bukkit 权限系统——Paper 平台可通过
+ * `permissions.yml` 静态声明或 LuckPerms 等权限管理插件管理。
+ *
+ * 粒度较粗（只声明默认值）；Yeow 生态内可由权限管理插件通过 `permissionCheck`
+ * 事件实现任意逻辑的权限管理。
+ */
+export function registerPermission(options: PermissionOptions, taskOptions?: TaskOptions): Permission {
+  const node = options?.node;
+  if (!node || typeof node !== 'string' || node.trim() === '') {
+    throw new Error('registerPermission: node is required');
+  }
+  const def: PermissionDefault = options.default || 'op';
+  if (!_registered[node]) {
+    call('permission.register', { node, default: def }, taskOptions);
+    _registered[node] = { node, default: def };
+  }
+  return _registered[node];
+}
+
+/** 权限节点对象 → 请求载荷（{ node, default }）；字符串包装为对象（default 默认 'op'）——Java 侧不做兼容。 */
+export function permissionPayload(perm: string | Permission | PermissionOptions): { node: string; default: PermissionDefault } {
+  if (typeof perm === 'string') return { node: perm, default: 'op' };
+  return { node: perm.node, default: perm.default || 'op' };
+}

package/src/player.ts

@@ -3,6 +3,7 @@ import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
 import type { ItemStack } from './item.js';
 import type { Message } from './message.js';
+import type { Permission } from './permission.js';
 
 interface PlayerData {
   uuid: string;
@@ -135,11 +136,12 @@ export class Player {
   }
   giveExp(amount: number, options?: TaskOptions): Promise<void> { return post('player.giveExp', { uuid: this.uuid, amount }, options); }
   giveExpSync(amount: number, options?: TaskOptions): void { call('player.giveExp', { uuid: this.uuid, amount }, options); }
-  hasPermission(node: string, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('player.hasPermission', { uuid: this.uuid, permission: node }, options);
+  /** 检查权限（经 Yeow 权限检查：`permissionCheck` 事件优先，无处理时回退 Bukkit）。node 可为权限节点对象。 */
+  hasPermission(node: string | Permission, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? node : { node: node.node } }, options);
   }
-  hasPermissionSync(node: string, options?: TaskOptions): boolean {
-    return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: node }, options);
+  hasPermissionSync(node: string | Permission, options?: TaskOptions): boolean {
+    return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: typeof node === 'string' ? node : { node: node.node } }, options);
   }
   /** 以玩家身份执行命令（**不含 `/` 前缀**，如 `say hi`；前缀会自动剥离；与服务器 `dispatchCommand`（控制台）相对）。 */
   performCommand(cmd: string, options?: TaskOptions): Promise<boolean> {