yeow-api 0.4.1 → 0.4.3

package/package.json

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

package/src/core.ts

@@ -57,8 +57,8 @@ export { assets, read as assetsRead, readSync as assetsReadSync,
 export { path } from './path.js';
 export { createReadStream, createWriteStream } from './fs.js';
 export type { ReadStream, WriteStream, ReadStreamOptions, WriteStreamOptions } from './fs.js';
-export { listen, respond, close, request, requestSync } from './http.js';
-export type { RespondOptions } from './http.js';
+export { listen, respond, close, request } from './http.js';
+export type { RespondOptions, RequestOptions, HttpResponse } from './http.js';
 export { logError } from './log-error.js';
 export { InstanceId, BossBarHandle, InventoryHandle } from './instance-id.js';
 export { ItemStack } from './item.js';

package/src/http.ts

@@ -22,6 +22,42 @@ export interface RespondOptions {
   headers?: Record<string, string>;
 }
 
+/** HTTP 请求选项（request）。 */
+export interface RequestOptions {
+  /** HTTP 方法（默认 `"GET"`）。 */
+  method?: string;
+  /** 请求头。 */
+  headers?: Record<string, string>;
+  /**
+   * 请求体（与 `fs.writeFile` 同语义）：`Uint8Array` 直接作为二进制；
+   * 字符串按 `encoding` 解释——缺省 UTF-8 文本，`'base64'` 时视为 base64 编码的二进制。
+   */
+  body?: string | Uint8Array;
+  /**
+   * 请求体（body 为字符串时）解释：`'utf8'`（默认）文本 / `'base64'` base64 二进制
+   * （与 `fs.writeFile` 同语义）。
+   */
+  encoding?: 'utf8' | 'base64';
+  /**
+   * 响应体形态：缺省 `Uint8Array`（原始字节，可在收到后自行解码，
+   * 如 `bytesToString(body)` 或 `new TextDecoder().decode(body)`）；
+   * `'utf8'` → UTF-8 字符串；`'base64'` → base64 字符串（原样返回，不解码）。
+   */
+  responseEncoding?: 'utf8' | 'base64';
+  /** 超时（毫秒）；缺省运行时默认（连接 5s / 读取 10s）。 */
+  timeout?: number;
+}
+
+/** HTTP 响应（request）。 */
+export interface HttpResponse {
+  /** HTTP 状态码。 */
+  status: number;
+  /** 响应头（键小写）。 */
+  headers: Record<string, string>;
+  /** 响应体：缺省 `Uint8Array`；`encoding: 'utf8' | 'base64'` 时为字符串。 */
+  body: string | Uint8Array;
+}
+
 function _sendHttp(payload: Record<string, unknown>): HttpResult {
   const r = $send('http', payload);
   if (!r) return {};
@@ -75,25 +111,49 @@ _registerCallback(() => {
 
 /**
  * 异步 HTTP 请求（不阻塞 JS 线程）——底层走 `http:requestAsync` 通道。
- * 推荐用于事件处理器与高频场景。需要同步阻塞返回的用 `requestSync`。
+ *
+ * 请求体与 `fs.writeFile` 同语义（`body: string | Uint8Array`，字符串按
+ * `encoding` 解释）；响应体默认 `Uint8Array`（原始字节），可用
+ * `responseEncoding` 直接得到字符串（`'utf8'` / `'base64'`），也可在收到后
+ * 用 `bytesToString` 自行解码。`timeout` 指定超时毫秒数（连接与读取，缺省
+ * 运行时默认）。
  */
-export function request(url: string, opts: Record<string, unknown> = {}): Promise<HttpResult> {
+export function request(url: string, opts: RequestOptions = {}): Promise<HttpResponse> {
   return new Promise((resolve, reject) => {
     const cbId = _registerCallback((result: unknown) => {
-      if ((result as any)?.err) reject(new Error((result as any).err));
-      else resolve(result as HttpResult);
+      const r = result as HttpResult;
+      if (r?.err || (r as any)?.error) {
+        reject(new Error(r?.err || (r as any).error));
+        return;
+      }
+      const body = r.body ?? '';
+      resolve({
+        status: r.status ?? 0,
+        headers: r.headers ?? {},
+        // 底层始终以 base64 承载原始字节；'utf8' 时 Java 侧已解码为文本，其余形态本地转换
+        body: opts.responseEncoding === 'utf8' ? body
+          : opts.responseEncoding === 'base64' ? body
+            : Uint8Array.fromBase64(body),
+      });
     });
     try {
-      _sendHttp({ t: 'requestAsync', p: { url, ...opts, cb: String(cbId) } });
+      const p: Record<string, unknown> = {
+        url,
+        method: opts.method || 'GET',
+        headers: opts.headers || {},
+      };
+      // 请求体与 fs.writeFile 同语义：Uint8Array 直接二进制（base64 承载）；
+      // 字符串按 encoding——缺省 UTF-8 文本，'base64' 视为 base64 二进制
+      if (opts.body instanceof Uint8Array) {
+        p.body = opts.body.toBase64();
+        p.encoding = 'base64';
+      } else {
+        p.body = opts.body ?? null;
+        if (opts.encoding === 'base64') p.encoding = 'base64';
+      }
+      p.responseType = opts.responseEncoding === 'utf8' ? 'text' : 'base64';
+      if (opts.timeout !== undefined) p.timeout = opts.timeout;
+      _sendHttp({ t: 'requestAsync', p: { ...p, cb: String(cbId) } });
     } catch (e) { reject(e); }
   });
 }
-
-/**
- * 同步 HTTP 请求（**阻塞 JS 线程**直到响应返回）——底层走 `http:request` 通道。
- * 阻塞期间 JS 线程无法处理事件/命令/回调（可能触发 event.timeout 告警）；
- * 仅适合低频、非事件上下文。事件处理器或高频场景请用 `request`（异步）或全局 `fetch`。
- */
-export function requestSync(url: string, opts: Record<string, unknown> = {}): HttpResult {
-  return _sendHttp({ t: 'request', p: { url, ...opts } });
-}

package/src/player.ts

@@ -2,6 +2,7 @@ import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
 import type { ItemStack } from './item.js';
+import { Block } from './block.js';
 import type { Message } from './message.js';
 import type { Permission } from './permission.js';
 import { Inventory } from './inventory.js';
@@ -170,6 +171,27 @@ export class Player {
   }
   teleport(loc: Location, options?: TaskOptions): Promise<void> { return post('player.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
   teleportSync(loc: Location, options?: TaskOptions): void { call('player.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
+  /** 向玩家发送假方块变化（仅客户端视觉，不改变真实世界）。block 为 Block 对象或字符串（同 world.setBlock，字符串无状态）。 */
+  sendBlockChange(location: Location, block: Block | string, options?: TaskOptions): Promise<void> {
+    const p: Record<string, unknown> = { uuid: this.uuid, ...location.toObject() };
+    if (typeof block === 'string') {
+      p.blockType = block;
+    } else {
+      p.blockType = block.type;
+      if (block.state && Object.keys(block.state).length > 0) p.state = block.state;
+    }
+    return post('player.sendBlockChange', p, options);
+  }
+  sendBlockChangeSync(location: Location, block: Block | string, options?: TaskOptions): void {
+    const p: Record<string, unknown> = { uuid: this.uuid, ...location.toObject() };
+    if (typeof block === 'string') {
+      p.blockType = block;
+    } else {
+      p.blockType = block.type;
+      if (block.state && Object.keys(block.state).length > 0) p.state = block.state;
+    }
+    call('player.sendBlockChange', p, options);
+  }
   sendActionBar(message: string | Message, options?: TaskOptions): Promise<void> { return post('player.sendActionBar', { uuid: this.uuid, message }, options); }
   sendActionBarSync(message: string | Message, options?: TaskOptions): void { call('player.sendActionBar', { uuid: this.uuid, message }, options); }
   sendResourcePack(url: string, hash?: string, prompt?: string | Message, force?: boolean, options?: TaskOptions): Promise<void> {