@shirokasoke/webapi-sdk 2.9.0-beta2-0.11-pre

package/dist/client.js

@@ -0,0 +1,668 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebApiError = exports.WebApiClient = void 0;
+const fetch_event_source_1 = require("@microsoft/fetch-event-source");
+function buildQuery(params) {
+    const record = params;
+    const qs = Object.entries(record)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+        .join("&");
+    return qs ? `?${qs}` : "";
+}
+/** 解包 `ApiResponse<T>`（如 SSE 事件帧），业务失败（success=false）时抛 {@link WebApiError} */
+function unwrapApiResponse(body) {
+    if (!body.success) {
+        throw new WebApiError(body.message, 200, body);
+    }
+    return body.data;
+}
+class WebApiClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.authToken = options.authToken;
+        const globalFetch = typeof globalThis !== "undefined" ? globalThis.fetch : undefined;
+        this.fetchImpl = options.fetch || globalFetch || undefined;
+        if (!this.fetchImpl) {
+            throw new Error("No fetch implementation provided. Pass one via options.fetch or run in an environment with global fetch.");
+        }
+    }
+    async request(path, init) {
+        const req = new Request(`${this.baseUrl}${path}`, init);
+        if (this.authToken) {
+            req.headers.set("Authorization", this.authToken);
+        }
+        const res = await this.fetchImpl(req);
+        const contentType = res.headers.get("content-type") || "";
+        if (!res.ok) {
+            if (contentType.includes("application/json")) {
+                const body = await res.json().catch(() => ({ message: res.statusText }));
+                throw new WebApiError(body.message || res.statusText, res.status, body);
+            }
+            throw new WebApiError(res.statusText, res.status);
+        }
+        if (contentType.includes("application/json")) {
+            const body = await res.json();
+            if (body.success) {
+                return body.data;
+            }
+            else {
+                throw new WebApiError(body.message, res.status, body);
+            }
+        }
+        return res.arrayBuffer();
+    }
+    /**
+     * SSE 订阅模板：统一处理鉴权头、响应校验、事件过滤与错误上报（基于 fetchEventSource，可携带
+     * Authorization 头，原生 EventSource 不支持）。服务端推送的 `error` 事件（纯文本消息）会转为
+     * {@link Error} 上报；连接建立后发生异常时同样上报并停止库内自动重连，由调用方决定是否重新订阅。
+     * @param url 完整订阅地址（含 query）
+     * @param eventName 业务事件名，其余事件将被忽略
+     * @param callback 业务数据回调
+     * @param errorCallback 出错回调，接收模板抛出或 `parse` 抛出的异常（如 {@link WebApiError}）
+     * @param parse 解析事件的 data 文本为业务数据，抛出异常表示该帧无效
+     * @returns AbortController，调用 `abort()` 可停止订阅
+     */
+    subscribeSse(url, eventName, callback, errorCallback, parse) {
+        const controller = new AbortController();
+        const headers = {};
+        if (this.authToken) {
+            headers["Authorization"] = this.authToken;
+        }
+        (0, fetch_event_source_1.fetchEventSource)(url, {
+            signal: controller.signal,
+            headers,
+            openWhenHidden: true,
+            fetch: this.fetchImpl,
+            onopen: async (response) => {
+                if (!response.ok) {
+                    const body = (await response.json().catch(() => null));
+                    throw new WebApiError(body?.message || response.statusText, response.status, body);
+                }
+                const contentType = response.headers.get("content-type") || "";
+                if (!contentType.includes("text/event-stream")) {
+                    throw new WebApiError(`Expected content-type to be text/event-stream, actual: ${contentType}`, response.status);
+                }
+            },
+            onmessage: (event) => {
+                if (event.event === "error") {
+                    errorCallback(new Error(event.data));
+                    return;
+                }
+                if (event.event !== eventName)
+                    return;
+                try {
+                    callback(parse(event.data));
+                }
+                catch (err) {
+                    errorCallback(err instanceof Error ? err : new Error(String(err)));
+                }
+            },
+            onerror: (err) => {
+                errorCallback(err instanceof Error ? err : new Error(String(err)));
+                // 停止库内自动重连，由调用方决定是否重新订阅
+                throw err;
+            },
+        }).catch(() => { });
+        return controller;
+    }
+    // region Root / Status
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/RootHandler.java)
+     * @returns 使用 {@link RootInfoSchema} 验证
+     */
+    getRoot() {
+        return this.request("/version");
+    }
+    // region TPS / Performance
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/TPSHandler.java)
+     * @returns 使用 `Joi.object().pattern(Joi.string(), {@link TPSInfoSchema})` 验证
+     */
+    getTPS() {
+        return this.request("/tps");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ProfilerHandler.java)
+     * @returns 使用 {@link ProfilerDataSchema} 验证
+     */
+    getProfiler() {
+        return this.request("/profiler");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/LagAnalyzerHandler.java)
+     * @returns 使用 {@link LagAnalyzerDataSchema} 验证
+     */
+    getLagAnalyzer() {
+        return this.request("/lag-analyzer");
+    }
+    // region World
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/WorldInfoHandler.java)
+     * @returns 使用 `Joi.object().pattern(Joi.string(), {@link WorldInfoDataSchema})` 验证
+     */
+    getWorldInfo() {
+        return this.request("/WorldInfo");
+    }
+    // region Blocks
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/BlocksHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link BlockSchema}`)` 验证
+     */
+    getBlocks() {
+        return this.request("/blocks");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/BlockHandler.java)
+     * @returns 使用 {@link BlockDetailSchema} 验证
+     */
+    getBlock(params) {
+        return this.request(`/block${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/SetBlockHandler.java)
+     * @param body 使用 {@link SetBlockBodySchema} 验证
+     * @returns 使用 {@link SetBlockResultSchema} 验证
+     */
+    setBlock(params, body) {
+        return this.request(`/setblock${buildQuery(params)}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * 提交批量 setblock 任务到慢队列，异步执行。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/BatchSetBlockHandler.java)
+     * @param tasks 使用 `Joi.array().items(`{@link BatchSetBlockTaskSchema} ) 验证
+     * @returns 使用 {@link BatchSetBlockSubmitResultSchema} 验证
+     */
+    batchSetBlock(tasks) {
+        return this.request("/batchsetblock", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(tasks),
+        });
+    }
+    /**
+     * 查询批量 setblock 任务执行结果。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/BatchSetBlockHandler.java)
+     * @returns 使用 {@link BatchSetBlockJobResultSchema} 验证
+     */
+    getBatchSetBlockJob(params) {
+        return this.request(`/batchsetblock${buildQuery(params)}`);
+    }
+    /**
+     * 轮询等待批量 setblock 任务完成。
+     * @param jobId 任务 ID（由 batchSetBlock 返回）
+     * @param intervalMs 轮询间隔 (ms)，默认 100
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/BatchSetBlockHandler.java)
+     * @returns 使用 {@link BatchSetBlockJobResultSchema} 验证
+     */
+    async waitForBatchSetBlockJob(jobId, intervalMs = 100) {
+        while (true) {
+            const job = await this.getBatchSetBlockJob({ id: jobId });
+            if (job.status === "completed")
+                return job;
+            await new Promise(r => setTimeout(r, intervalMs));
+        }
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/FMPHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link FMPPartSchema}`)` 验证
+     */
+    getBlockFMP(params) {
+        return this.request(`/block/fmp${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/block/BlockTileHandler.java)
+     * @returns 二进制数据，无 JSON Schema
+     */
+    getBlockTile(params) {
+        return this.request(`/block/tile${buildQuery(params)}`);
+    }
+    // region Items
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/item/ItemsHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link ItemSchema}`)` 验证
+     */
+    getItems() {
+        return this.request("/items");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/item/ItemHandler.java)
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/item/ItemStaticHandler.java)
+     * @returns 使用 {@link ItemDetailSchema} 验证
+     */
+    getItem(params) {
+        return this.request(`/item${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/item/ItemIconHandler.java)
+     * @param params.id 物品 ID（对应 ItemStack 的 id）
+     * @param params.damage 物品损伤值/元数据（可选，默认 0）
+     * @param params.tag Base64 编码的 NBTTagCompound（可选）
+     * @returns 二进制 PNG 图片数据 (ArrayBuffer)
+     */
+    getItemIcon(params) {
+        return this.request(`/item/icon${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/item/AEHandler.java)
+     * @returns 使用 {@link AEItemDefinitionsSchema} 验证
+     */
+    getAEItemsDef() {
+        return this.request("/items/ae");
+    }
+    // region Fluids
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/fluid/FluidsHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link FluidSchema}`)` 验证
+     */
+    getFluids() {
+        return this.request("/fluids");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/fluid/FluidContainersHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link FluidContainerSchema}`)` 验证
+     */
+    getFluidContainers() {
+        return this.request("/fluidContainers");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/fluid/FluidIconHandler.java)
+     * @param params.id 流体 ID（对应 Fluid 的 id）
+     * @param params.name 流体名称（对应 Fluid 的 name）
+     * @returns 二进制 PNG 图片数据 (ArrayBuffer)
+     */
+    getFluidIcon(params) {
+        return this.request(`/fluid/icon${buildQuery(params)}`);
+    }
+    // region Entities
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/entity/EntitiesHandler.java)
+     * @returns 使用 `Joi.object().pattern(Joi.string(),`{@link EntitiesByDimensionSchema}`)` 验证
+     *
+     * 其中实体为 {@link EntitySummarySchema} 精简结构
+     */
+    getEntities() {
+        return this.request("/entities");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/entity/EntityHandler.java)
+     * @returns 使用 {@link EntitySchema} 验证
+     */
+    getEntity(params) {
+        return this.request(`/entity${buildQuery(params)}`);
+    }
+    // region Chunks
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/chunk/ChunksHandler.java)
+     * @returns 使用 `Joi.object().pattern(Joi.string(),`{@link ChunksByDimensionSchema}`)` 验证
+     */
+    getChunks() {
+        return this.request("/chunks");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/chunk/ChunkHandler.java)
+     * @returns 使用 {@link ChunkWithDimensionSchema} 验证
+     */
+    getChunk(params) {
+        return this.request(`/chunk${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/chunk/ChunkMapHandler.java)
+     * @returns JSON 模式使用 `Joi.array().items(Joi.array().items(`{@link ChunkMapCellSchema}`)` 验证；raw 模式为 ArrayBuffer
+     */
+    getChunkMap(params, raw) {
+        const q = buildQuery({
+            ...params,
+            raw: raw == true ? String(raw) : undefined,
+        });
+        return this.request(`/chunk/map${q}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/chunk/ChunkForceHandler.java)
+     * @returns 使用 {@link ChunkForceListSchema} 验证
+     */
+    getChunkForceList() {
+        return this.request("/chunk/force");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/chunk/ChunkForceHandler.java)
+     * @returns 使用 {@link ChunkLoadResultSchema} 验证
+     */
+    loadChunk(params) {
+        return this.request(`/chunk/force${buildQuery({ action: "load", ...params })}`, {
+            method: "POST",
+        });
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/chunk/ChunkForceHandler.java)
+     * @returns 使用 {@link ChunkLoadResultSchema} 验证
+     */
+    unloadChunk(params) {
+        return this.request(`/chunk/force${buildQuery({ action: "unload", ...params })}`, {
+            method: "POST",
+        });
+    }
+    // region GT5
+    /**
+     * 查询单个 GT5 机器信息。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5BaseHandler.java)
+     * @returns 使用 {@link GT5MachineInfoSchema} 验证
+     */
+    getGT5Machine(params) {
+        return this.request(`/gt5${buildQuery(params)}`);
+    }
+    /**
+     * 提交批量 GT5 机器查询任务。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5BatchHandler.java)
+     * @param machines 使用 `Joi.array().items(`{@link GT5BatchMachineCoordSchema}`)` 验证
+     * @returns 使用 {@link GT5BatchSubmitResultSchema} 验证
+     */
+    submitGT5Batch(machines) {
+        return this.request("/gt5/batch", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(machines),
+        });
+    }
+    /**
+     * 查询批量 GT5 机器任务状态。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5BatchHandler.java)
+     * @returns 使用 {@link GT5BatchJobResultSchema} 验证
+     */
+    getGT5BatchJob(params) {
+        return this.request(`/gt5/batch${buildQuery(params)}`);
+    }
+    /**
+     * 重新执行已有的批量 GT5 机器查询任务。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5BatchHandler.java)
+     * @returns 使用 {@link GT5BatchRerunResultSchema} 验证
+     */
+    rerunGT5Batch(params) {
+        return this.request(`/gt5/batch${buildQuery(params)}`, {
+            method: "PATCH",
+        });
+    }
+    /**
+     * 轮询等待批量 GT5 机器任务完成。
+     * @param jobId 任务 ID（由 submitGT5Batch 返回）
+     * @param intervalMs 轮询间隔 (ms)，默认 100
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5BatchHandler.java)
+     * @returns 使用 {@link GT5BatchJobResultSchema} 验证
+     */
+    async waitForGT5BatchJob(jobId, intervalMs = 100) {
+        while (true) {
+            const job = await this.getGT5BatchJob({ id: jobId });
+            if (job.status === "completed")
+                return job;
+            await new Promise(r => setTimeout(r, intervalMs));
+        }
+    }
+    /**
+     * 提交区块扫描任务，异步扫描指定区块内所有 GT5 机器。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5ChunkScanHandler.java)
+     * @returns 使用 {@link GT5ScanSubmitResultSchema} 验证
+     */
+    submitGT5ChunkScan(params) {
+        return this.request(`/gt5/scan${buildQuery(params)}`, {
+            method: "POST",
+        });
+    }
+    /**
+     * 查询区块扫描任务状态。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5ChunkScanHandler.java)
+     * @returns 使用 {@link GT5ScanJobResultSchema} 验证
+     */
+    getGT5ScanJob(params) {
+        return this.request(`/gt5/scan${buildQuery(params)}`);
+    }
+    /**
+     * 轮询等待区块扫描任务完成。
+     * @param jobId 任务 ID（由 submitGT5ChunkScan 返回）
+     * @param intervalMs 轮询间隔 (ms)，默认 100
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/gt5/GT5ChunkScanHandler.java)
+     * @returns 使用 {@link GT5ScanJobResultSchema} 验证
+     */
+    async waitForGT5ScanJob(jobId, intervalMs = 100) {
+        while (true) {
+            const job = await this.getGT5ScanJob({ id: jobId });
+            if (job.status === "completed")
+                return job;
+            await new Promise(r => setTimeout(r, intervalMs));
+        }
+    }
+    // region AE2
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEBaseHandler.java)
+     * @returns 使用 {@link AEHitResultSchema} 验证
+     */
+    aeHit(params) {
+        return this.request(`/ae${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AENodesHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link AENodeSchema}`)` 验证
+     */
+    aeNodes(params) {
+        return this.request(`/ae/nodes${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AECPUHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link AECPUSchema}`)` 验证
+     */
+    aeCPUs(params) {
+        return this.request(`/ae/cpu${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEMEHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link AE2PatternSchema}`.append({ slot: Joi.number().required(), direction: Joi.string().optional() }))` 验证
+     */
+    aeME(params) {
+        return this.request(`/ae/me${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEMEsHandler.java)
+     * @returns 使用 `Joi.array().items(`{@link AEMEInterfaceSchema}`)` 验证
+     */
+    aeMEs(params) {
+        if (params.load || params.world) {
+            params.pattern = true;
+        }
+        return this.request(`/ae/mes${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEMEsupportHandler.java)
+     * @returns 字符串数组，无专用 Schema
+     */
+    aeMESupport() {
+        return this.request("/ae/me/support");
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEItemHandler.java)
+     * @returns 使用 {@link AEItemsResultSchema} 验证
+     */
+    aeItems(params) {
+        return this.request(`/ae/item${buildQuery(params)}`);
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AECPUTaskHandler.java)
+     * @param body 使用 {@link AECraftingTaskBodySchema} 验证
+     * @returns 使用 {@link AECraftingTaskResultSchema} 验证
+     */
+    aeCraft(params, body) {
+        return this.request(`/ae/cpu/task${buildQuery(params)}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AECPUCancelHandler.java)
+     * @param body 使用 {@link AECPUCancelBodySchema} 验证
+     * @returns 使用 {@link AECPUCancelResultSchema} 验证
+     */
+    aeCancel(params, body) {
+        return this.request(`/ae/cpu/cancel${buildQuery(params)}`, {
+            method: "DELETE",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * 构建 AE 库存 SSE（Server-Sent Events）订阅地址。
+     * 注意：仅当服务端启用虚拟线程（useVirtualThreads）时该路由才会注册。
+     * 返回 EventSource 可直接使用的完整 URL。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEItemSSEHandler.java)
+     */
+    aeItemsSseUrl(params) {
+        return `${this.baseUrl}/ae/item/sse${buildQuery(params)}`;
+    }
+    /**
+     * 以回调方式订阅 AE 库存 SSE 推送（基于 fetchEventSource，可携带 Authorization 头，原生 EventSource 不支持）。
+     * 服务端周期性推送 `aeitem` 事件（`ApiResponse<{@link AEItemsResult}>` JSON，间隔由服务端 AE2Config.item.interval 决定），
+     * 回调收到解包后的 {@link AEItemsResult}，业务失败（success=false）时以 {@link WebApiError} 上报；
+     * 连接建立后发生异常时推送 `error` 事件（纯文本消息）并关闭连接。
+     * @param params 目标方块坐标
+     * @param callback 每次收到库存快照时调用
+     * @param errorCallback 出错（网络错误、鉴权失败、服务端 error 事件、业务失败、数据解析失败）时调用，库内自动重连会随之停止
+     * @returns AbortController，调用 `abort()` 可停止订阅
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AEItemSSEHandler.java)
+     */
+    aeItemSseCallback(params, callback, errorCallback) {
+        return this.subscribeSse(`${this.baseUrl}/ae/item/sse${buildQuery(params)}`, "aeitem", callback, errorCallback, raw => unwrapApiResponse(JSON.parse(raw)));
+    }
+    /**
+     * 构建 AE 合成 CPU 状态 SSE（Server-Sent Events）订阅地址。
+     * 注意：仅当服务端启用虚拟线程（useVirtualThreads）时该路由才会注册。
+     * 返回 EventSource 可直接使用的完整 URL。
+     * @param params 目标方块坐标；interval 为推送间隔（秒），省略时由服务端取默认值 5
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AECPUSSEHandler.java)
+     */
+    aeCpuSseUrl(params) {
+        return `${this.baseUrl}/ae/cpu/sse${buildQuery(params)}`;
+    }
+    /**
+     * 以回调方式订阅 AE 合成 CPU 状态 SSE 推送（基于 fetchEventSource，可携带 Authorization 头，原生 EventSource 不支持）。
+     * 服务端周期性推送 `aecpu` 事件（{@link AECPU} 数组 JSON，间隔由 interval 参数（秒）决定，服务端默认 5），
+     * 回调收到 CPU 状态列表；连接建立后发生异常时推送 `error` 事件（纯文本消息）并关闭连接。
+     * @param params 目标方块坐标；interval 为推送间隔（秒），省略时由服务端取默认值
+     * @param callback 每次收到 CPU 状态快照时调用
+     * @param errorCallback 出错（网络错误、鉴权失败、服务端 error 事件、业务失败、数据解析失败）时调用，库内自动重连会随之停止
+     * @returns AbortController，调用 `abort()` 可停止订阅
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ae2/AECPUSSEHandler.java)
+     */
+    aeCpuSseCallback(params, callback, errorCallback) {
+        return this.subscribeSse(`${this.baseUrl}/ae/cpu/sse${buildQuery(params)}`, "aecpu", callback, errorCallback, raw => {
+            const body = JSON.parse(raw);
+            // 服务端当前推送裸数组，同时兼容 ApiResponse 包装形式
+            return Array.isArray(body) ? body : unwrapApiResponse(body);
+        });
+    }
+    // region Recipes
+    /**
+     * 查询工作台合成配方（有序/无序）。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/recipe/CraftingRecipesHandler.java)
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/recipe/IndexedCraftingRecipesHandler.java)
+     * @returns 使用 {@link CraftingRecipesResultSchema} 验证
+     */
+    getCraftingRecipes(params) {
+        return this.request(`/recipes/crafting${buildQuery(params ?? {})}`);
+    }
+    /**
+     * 查询熔炉熔炼配方。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/recipe/FurnaceRecipesHandler.java)
+     * @returns 使用 {@link FurnaceRecipesResultSchema} 验证
+     */
+    getFurnaceRecipes(params) {
+        return this.request(`/recipes/furnace${buildQuery(params ?? {})}`);
+    }
+    /**
+     * 查询 GT5 配方表的映射表（unlocalizedName → 显示名）。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/recipe/GTmaps.java)
+     * @returns 使用 `Joi.array().items(`{@link GTRecipeMapSchema}`)` 验证
+     */
+    getGTRecipeMaps() {
+        return this.request("/recipes/gt/maps");
+    }
+    /**
+     * 查询 GT5 机器配方。
+     * 注意：必须至少提供 id/damage（物品）、fluid（流体）或 map（单个配方表）之一。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/recipe/GTRecipesHandler.java)
+     * @returns 使用 {@link GTRecipesResultSchema} 验证
+     */
+    getGTRecipes(params) {
+        return this.request(`/recipes/gt${buildQuery(params)}`);
+    }
+    // region 3D Print
+    /**
+     * 上传图片 → OC 3D 打印件，投递到玩家背包（多余掉落在玩家附近）。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ThreeD/PlayerPrintHandler.java)
+     * @param params 二选一：id（实体 ID）或 name（玩家名）
+     * @param image 图片二进制数据（png/jpg 等）
+     * @returns 使用 {@link PlayerPrintResultSchema} 验证
+     */
+    printToPlayer(params, image) {
+        return this.request(`/3d/player${buildQuery(params)}`, {
+            method: "PUT",
+            body: image,
+        });
+    }
+    /**
+     * 上传图片 → 在世界中铺设 OC 3D 打印像素画（慢队列逐块执行）。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ThreeD/WorldPrintHandler.java)
+     * @returns 使用 {@link WorldPrintSubmitResultSchema} 验证
+     */
+    submitWorldPrint(params, image) {
+        return this.request(`/3d/world${buildQuery(params)}`, {
+            method: "PUT",
+            body: image,
+        });
+    }
+    /**
+     * 查询世界 3D 打印任务进度。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ThreeD/WorldPrintHandler.java)
+     * @returns 使用 {@link WorldPrintJobResultSchema} 验证
+     */
+    getWorldPrintJob(params) {
+        return this.request(`/3d/world${buildQuery(params)}`);
+    }
+    /**
+     * 轮询等待世界 3D 打印任务完成。
+     * @param jobId 任务 ID（由 submitWorldPrint 返回）
+     * @param intervalMs 轮询间隔 (ms)，默认 100
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ThreeD/WorldPrintHandler.java)
+     * @returns 使用 {@link WorldPrintJobResultSchema} 验证
+     */
+    async waitForWorldPrintJob(jobId, intervalMs = 100) {
+        while (true) {
+            const job = await this.getWorldPrintJob({ id: jobId });
+            if (job.status === "completed")
+                return job;
+            await new Promise(r => setTimeout(r, intervalMs));
+        }
+    }
+    /**
+     * 上传图片，估算生成的 3D 打印件 NBT 大小（不实际打印）。
+     * @java [java](../../../src/main/java/love/shirokasoke/webapi/webserver/handlers/ThreeD/PrintSizeHandler.java)
+     * @returns 使用 {@link PrintSizeResultSchema} 验证
+     */
+    getPrintSize(image, params) {
+        return this.request(`/3d/size${buildQuery(params ?? {})}`, {
+            method: "PUT",
+            body: image,
+        });
+    }
+}
+exports.WebApiClient = WebApiClient;
+class WebApiError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "WebApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.WebApiError = WebApiError;