@sokel-dev/plugin-sdk 0.3.0 → 0.5.3

package/dist/src/plugin.js

@@ -1,8 +1,11 @@
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
 /**
- * Plugin：注册表 + 分发。传输无关——NATS 那一层只负责收发字节。
+ * Plugin: the registry plus dispatch. Transport-agnostic — the NATS layer only moves bytes.
  *
- * 分发这段是**最值得单测的一段**（未知操作、流式与非流式的回复形态、webhook 帧的拦截），
- * 所以它一行都不碰 NATS：测试塞一个假 sink 就能跑完整条路径。
+ * Dispatch is the part **most worth unit-testing** (unknown operations, the reply shape for
+ * streaming versus non-streaming, intercepting the webhook frame), so it touches no NATS at all: a
+ * fake sink is enough to exercise the whole path.
  */
 import { CAP_WEBHOOK, Contract, OP_AUTH_POLL, OP_AUTH_START, OP_AUTH_SUBMIT } from "./contract.js";
 import { CONFIRMED, PENDING } from "./auth.js";
@@ -26,44 +29,49 @@ export class Plugin {
         this.name = cfg.name || cfg.contract.name || "sokel-plugin";
         this.endpoint = cfg.endpoint || envOr("ENDPOINT", "http://localhost:8088");
         this.token = cfg.token || env("TOKEN");
-        // 版本三档：显式参数 > 契约里声明的（sokel.yaml 的 plugin.version）> 环境变量 > 兜底
+        // Version, in order of precedence: explicit argument > the contract's plugin.version >
+        // environment variable > fallback
         this.version = cfg.version || cfg.contract.version || env("VERSION") || "sdk-node";
     }
-    /** 低阶注册：fn(ctx, input, emitter)。生成的 onXxx 就是它的类型化外壳。 */
+    /** Low-level registration: fn(ctx, input, emitter). The generated onXxx is its typed shell. */
     register(opId, fn) {
         if (!opId.includes(".") && !this.contract.operation(opId)) {
-            throw new Error(`操作 "${opId}" 不在契约里 —— 先在 sokel.yaml 的 operations 声明它，再重新生成`);
+            throw new Error(`operation "${opId}" is not in the contract — declare it under operations in manifest.yml and regenerate`);
         }
         if (this.ops.has(opId))
-            throw new Error(`操作 "${opId}" 重复注册`);
+            throw new Error(`operation "${opId}" registered twice`);
         this.ops.set(opId, fn);
     }
-    /** 注册常驻事件源；run() 时每个「源 × 凭证」起一个任务。 */
+    /** Register a long-running event source; run() starts one task per source × credential. */
     registerSource(id, label, fn) {
         this.sources.push({ id, label, fn });
     }
-    /** 注册 webhook 处理器（一个插件一个：按 header / path 自行分流上游事件类型）。 */
+    /** Register the webhook handler (one per plugin: route upstream event types yourself by header
+     * or path). */
     registerWebhook(fn) {
         this.webhookFn = fn;
-        // 能力位不靠自报靠事实：注册了处理器就是支持，作者忘声明不该让入口按钮消失
+        // The capability follows the fact, not a declaration: registering a handler *is* support.
+        // Forgetting to declare it should never make the entry-point button disappear.
         this.contract.data.capabilities = { ...(this.contract.data.capabilities ?? {}), [CAP_WEBHOOK]: true };
     }
     get hasWebhook() {
         return this.webhookFn !== undefined;
     }
     /**
-     * 挂上认证流的实现。形态（qr / input / oauth）在 sokel.yaml 里声明，这里只给实现。
+     * Attach the auth flow's implementation. The shape (qr / input / oauth) is declared in manifest.yml;
+     * only the implementation goes here.
      *
-     * kind=oauth 的 start/poll 由**平台代答**（client_secret 在平台手里，插件构造不出
-     * 同意页地址），所以那种插件一个 handler 都不用写。
+     * For kind=oauth the platform answers start/poll itself — the client secret lives there and a
+     * plugin cannot build the consent URL — so such a plugin writes no handler at all.
      */
     registerAuth(h) {
         const declared = this.contract.data.auth_flow;
         const steps = declared?.steps ?? [];
         const requireStep = (step) => {
             if (!steps.includes(step)) {
-                throw new Error(`契约里的认证流没有 "${step}" 这一步（当前 ${steps.join("/") || "未声明"}）——` +
-                    "步骤由 credential.auth.kind 定死，实现多于声明就是一份永远不会被调用的代码");
+                throw new Error(`the contract's auth flow has no "${step}" step (it has ${steps.join("/") || "none"}) — ` +
+                    "the steps follow from credential.auth.kind, and implementing more than was declared " +
+                    "means writing code that will never be called");
             }
         };
         if (h.start) {
@@ -71,7 +79,7 @@ export class Plugin {
             this.ops.set(OP_AUTH_START, async (ctx, _in, out) => {
                 const ch = await h.start(ctx);
                 if (!ch)
-                    throw new Error("认证流 start 未返回挑战");
+                    throw new Error("the auth flow's start returned no challenge");
                 out.vars({
                     auth_id: ch.authId || `auth_${Date.now()}`,
                     challenge: { kind: ch.kind ?? declared?.kind ?? "", qr_image: ch.qrImage ?? "", prompt: ch.prompt ?? "" },
@@ -84,7 +92,8 @@ export class Plugin {
             this.ops.set(OP_AUTH_POLL, async (ctx, input, out) => {
                 const st = (await h.poll(ctx, String(input.auth_id ?? ""))) ?? { status: PENDING };
                 const vars = { status: st.status };
-                // session 只在 confirmed 时带出去；pending 时带一个 null 会让平台反复覆写凭证行
+                // Only carry the session once confirmed: handing back a null while pending makes the
+                // platform rewrite the credential row over and over.
                 if (st.status === CONFIRMED && st.session)
                     vars.session = st.session;
                 out.vars(vars);
@@ -98,22 +107,24 @@ export class Plugin {
             });
         }
     }
-    /** 声明本插件支持/不支持哪些**可选**能力（同一个操作做到什么程度）。 */
+    /** Declare which **optional** capabilities this plugin has — how far a given operation goes. */
     setCapabilities(caps) {
         this.contract.data.capabilities = { ...(this.contract.data.capabilities ?? {}), ...caps };
     }
     /**
-     * 注册 / 心跳的载荷（协议 §3）。
+     * The registration / heartbeat payload (protocol §3).
      *
-     * 单独一个方法是为了能测：**声明了却没上报**是这套自报机制最典型的静默失效——
-     * 插件侧一切正常、平台侧什么也没发生，作者只能对着一个没反应的界面排查。
+     * It is a separate method so it can be tested: **declared but never reported** is the classic
+     * silent failure of a self-reporting mechanism. Everything looks fine on the plugin side, nothing
+     * happens on the platform side, and the author is left staring at an inert UI.
      */
     registerPayload(instanceId, host, startedAt) {
         const body = {
             token: this.token,
             instance_id: instanceId,
             host,
-            // 进程启动时刻：注册与每拍心跳重发同一值，平台据此区分「重新上线的新副本」与「一直活着的老副本」
+            // Process start time: registration and every heartbeat resend the same value, which is how
+            // the platform tells "a new replica came up" from "the old one is still alive".
             started_at: startedAt,
             version: this.version,
             transport: "nats",
@@ -131,11 +142,13 @@ export class Plugin {
         const fn = this.ops.get(opId);
         if (fn)
             return fn;
-        // 单操作插件：operation 省略（或对不上）时默认唯一操作，与 Go SDK 同一条兜底
+        // Single-operation plugin: when `operation` is missing (or unknown), fall back to the only one
+        // there is — the same fallback the Go SDK has.
         const business = [...this.ops.keys()].filter((k) => !k.includes("."));
         return business.length === 1 ? this.ops.get(business[0]) : undefined;
     }
-    /** 跑一次调用，把各帧交给 sink。异常原样抛出，由传输层翻成 error 帧 / error 回复。 */
+    /** Run one call, handing frames to the sink. Exceptions propagate; the transport turns them into
+     * an error frame or an error reply. */
     async dispatch(call, sink, files) {
         const opId = call.operation ?? "";
         const fn = this.find(opId);
@@ -144,19 +157,19 @@ export class Plugin {
         const ctx = new Ctx({ credential: call.credential, trace: call.trace, files });
         await fn(ctx, call.input ?? {}, new Emitter(sink));
     }
-    /** 非流式：缓冲各帧，合并 variables 作为单次回复。 */
+    /** Non-streaming: buffer the frames and merge the variables into a single reply. */
     async dispatchBuffered(call, files) {
         const buf = new BufferSink();
         await this.dispatch(call, buf.sink, files);
         return buf.vars;
     }
     /**
-     * 处理一帧 __webhook__。应答带 events 计数——平台的 webhook 面板靠它回答
-     * 「请求到了但为什么没起工作流」这一问。
+     * Handle one __webhook__ frame. The reply carries an events count: that is how the platform's
+     * webhook panel answers "the request arrived, so why did no workflow start?".
      */
     async handleWebhook(sctx, frame) {
         if (!this.webhookFn)
-            return { status: 0, error: "插件未注册 webhook 处理器" };
+            return { status: 0, error: "the plugin registered no webhook handler" };
         const req = new WebhookRequest(frame ?? {});
         let events = 0;
         const counted = new Proxy(sctx, {
@@ -179,7 +192,7 @@ export class Plugin {
             return { status: 0, error: `${e instanceof Error ? e.message : e}` };
         }
     }
-    /** 连接平台、注册、心跳、分发调用。返回的 Promise 在收到 SIGINT/SIGTERM 后完成。 */
+    /** Connect, register, heartbeat and dispatch calls. The promise settles on SIGINT/SIGTERM. */
     async run() {
         const { NatsTransport } = await import("./nats.js");
         await new NatsTransport().run(this);

package/dist/src/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime.d.ts

@@ -1,24 +1,25 @@
 /**
- * 运行时形状：文件引用、产出帧、调用上下文。
+ * Runtime shapes: file references, output frames, the call context.
  *
- * 与传输无关——NATS 只提供「取字节 / 存字节 / 发帧」三个回调，剩下的语义都在这里。
- * 测试因此不需要 broker：塞一个假的文件运行时与假的 sink 就能跑完整条分发路径。
+ * Transport-agnostic — NATS supplies only three callbacks (fetch bytes, store bytes, emit a frame);
+ * every other semantic lives here. That is why tests need no broker: a fake file runtime and a fake
+ * sink are enough to exercise the whole dispatch path.
  */
-/** 文件引用（画布里只流转引用，不内联字节）。 */
+/** A file reference. Only the reference travels through the canvas; bytes never inline. */
 export interface SokelFile {
     id?: string;
     url?: string;
     name?: string;
     mime?: string;
     size?: number;
-    /** data：无平台文件层时（单元测试）直接携带的字节，不参与序列化。 */
+    /** Bytes carried directly when there is no platform file layer (unit tests). Not serialized. */
     data?: Uint8Array;
 }
-/** 文件字节的取/存后端，由传输层注入。 */
+/** The fetch/store backend for file bytes, injected by the transport. */
 export interface FileRuntime {
     fetch(f: SokelFile): Promise<Uint8Array>;
     store(name: string, mime: string, data: Uint8Array): Promise<SokelFile>;
-    /** 边读边传：内存占用恒为一个块，与文件大小无关。 */
+    /** Stream while reading: memory stays at one chunk regardless of file size. */
     storeStream(name: string, mime: string, src: AsyncIterable<Uint8Array>): Promise<SokelFile>;
 }
 export declare const FRAME_TEXT = "text";
@@ -31,24 +32,27 @@ export interface Frame {
     vars?: Record<string, unknown>;
 }
 export type Sink = (f: Frame) => void;
-/** 类型化产出器。多次调用 = 多帧（流式）；非流式由 SDK 缓冲合并成一次回复。 */
+/** Typed emitter. Each call is one frame (streaming); for non-streaming operations the SDK buffers
+ * the frames and merges them into a single reply. */
 export declare class Emitter<Out> {
     private readonly sink;
     constructor(sink: Sink);
-    /** 人类可读文本（展示 / tracing）。 */
+    /** Human-readable text (display / tracing). */
     text(s: string): void;
-    /** 结构化 JSON（展示 / tracing）。 */
+    /** Structured JSON (display / tracing). */
     json(v: unknown): void;
-    /** 类型化输出变量（进下游节点）。可多次调用，后帧覆盖同名字段。 */
+    /** Typed output variables (they flow downstream). May be called repeatedly; a later frame
+     * overwrites same-named fields. */
     vars(out: Out): void;
 }
 export declare function toVars(value: unknown): Record<string, unknown>;
-/** 非流式汇聚：只收 variables 帧，合并成一个输出对象（text/json 仅流式展示用）。 */
+/** Non-streaming sink: keeps only variables frames and merges them into one output object.
+ * text/json frames exist for streaming display only. */
 export declare class BufferSink {
     readonly vars: Record<string, unknown>;
     readonly sink: Sink;
 }
-/** 操作 handler 的上下文：凭证、追踪、文件取存。 */
+/** The context handed to an operation handler: credentials, tracing, file fetch/store. */
 export declare class Ctx {
     readonly credential: Record<string, string>;
     private readonly traceMap;
@@ -59,26 +63,29 @@ export declare class Ctx {
         files?: FileRuntime;
     });
     /**
-     * 平台下发的追踪上下文（run_id / workflow_id / node_id）。
+     * Tracing context supplied by the platform (run_id / workflow_id / node_id).
      *
-     * 非工作流调用（试调用、健康检查）没有这些值，返回空串——**调用方要把空串当
-     * 「没有重试语义」处理**，而不是当成一个恒定的键（那会把两次独立调用错误地去重）。
+     * Calls outside a workflow (console tests, health checks) have none of these and get "" back.
+     * **Treat "" as "no retry semantics"**, never as a constant key — doing the latter would
+     * deduplicate two independent calls into one.
      */
     trace(key: string): string;
     /**
-     * 凭证按类型化形状读出。返回 Partial<T> 而不是 T —— 平台下发的是「这条凭证有哪些字段」，
-     * 生成的 Credential 里标必填的字段在运行时仍可能缺（凭证刚建、还没登录）。
-     * 假装它一定在，只会把一次 undefined 推迟到更远的地方炸。
+     * Read the credential into a typed shape. It returns Partial<T> rather than T: the platform sends
+     * whichever fields that credential row has, and a field the generated Credential marks required
+     * can still be missing at runtime (a freshly created credential, one that has not logged in yet).
+     * Pretending otherwise only moves the undefined further from where it will explode.
      */
     credentialAs<T extends object>(): Partial<T>;
     fetch(f: SokelFile): Promise<Uint8Array>;
-    /** 产出一个文件：字节交回平台登记，返回可放进出参的引用。 */
+    /** Produce a file: hand the bytes back to the platform and get a reference for the output. */
     upload(name: string, mime: string, data: Uint8Array): Promise<SokelFile>;
     /**
-     * 边读边传本地文件：内存占用恒为一个块（1 MiB），与文件大小无关。
+     * Stream a local file: memory stays at one chunk (1 MiB) regardless of file size.
      *
-     * 几百 MB 以上的东西（视频、压缩包、数据集）一律走它——upload() 要先把整个文件
-     * 读进内存，那会把插件进程撑爆，而症状是「大文件时容器莫名其妙被 OOM 杀掉」。
+     * Anything above a few hundred megabytes (video, archives, datasets) belongs here. upload() reads
+     * the whole file into memory first, and the symptom of that is a container mysteriously killed by
+     * the OOM reaper on large inputs.
      */
     uploadFile(path: string, name?: string, mime?: string): Promise<SokelFile>;
 }

package/dist/src/runtime.js

@@ -1,10 +1,7 @@
-/**
- * 运行时形状：文件引用、产出帧、调用上下文。
- *
- * 与传输无关——NATS 只提供「取字节 / 存字节 / 发帧」三个回调，剩下的语义都在这里。
- * 测试因此不需要 broker：塞一个假的文件运行时与假的 sink 就能跑完整条分发路径。
- */
-// 够用就行：猜不出来的落 application/octet-stream，平台不会因此少存一个字节。
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
+// Good enough: anything unrecognised becomes application/octet-stream, and the platform stores
+// exactly the same bytes either way.
 const MIME_BY_EXT = {
     ".mp4": "video/mp4", ".webm": "video/webm", ".mkv": "video/x-matroska", ".mov": "video/quicktime",
     ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".opus": "audio/opus", ".wav": "audio/wav",
@@ -15,21 +12,23 @@ const MIME_BY_EXT = {
 export const FRAME_TEXT = "text";
 export const FRAME_JSON = "json";
 export const FRAME_VARS = "variables";
-/** 类型化产出器。多次调用 = 多帧（流式）；非流式由 SDK 缓冲合并成一次回复。 */
+/** Typed emitter. Each call is one frame (streaming); for non-streaming operations the SDK buffers
+ * the frames and merges them into a single reply. */
 export class Emitter {
     sink;
     constructor(sink) {
         this.sink = sink;
     }
-    /** 人类可读文本（展示 / tracing）。 */
+    /** Human-readable text (display / tracing). */
     text(s) {
         this.sink({ kind: FRAME_TEXT, text: s });
     }
-    /** 结构化 JSON（展示 / tracing）。 */
+    /** Structured JSON (display / tracing). */
     json(v) {
         this.sink({ kind: FRAME_JSON, json: v });
     }
-    /** 类型化输出变量（进下游节点）。可多次调用，后帧覆盖同名字段。 */
+    /** Typed output variables (they flow downstream). May be called repeatedly; a later frame
+     * overwrites same-named fields. */
     vars(out) {
         const m = toVars(out);
         if (Object.keys(m).length > 0)
@@ -40,7 +39,7 @@ export function toVars(value) {
     if (value === null || value === undefined)
         return {};
     if (typeof value !== "object" || Array.isArray(value)) {
-        throw new TypeError(`输出必须是对象，收到 ${typeof value}`);
+        throw new TypeError(`output must be an object, got ${typeof value}`);
     }
     const out = {};
     for (const [k, v] of Object.entries(value)) {
@@ -49,7 +48,8 @@ export function toVars(value) {
     }
     return out;
 }
-/** 非流式汇聚：只收 variables 帧，合并成一个输出对象（text/json 仅流式展示用）。 */
+/** Non-streaming sink: keeps only variables frames and merges them into one output object.
+ * text/json frames exist for streaming display only. */
 export class BufferSink {
     vars = {};
     sink = (f) => {
@@ -58,7 +58,7 @@ export class BufferSink {
         Object.assign(this.vars, f.vars ?? {});
     };
 }
-/** 操作 handler 的上下文：凭证、追踪、文件取存。 */
+/** The context handed to an operation handler: credentials, tracing, file fetch/store. */
 export class Ctx {
     credential;
     traceMap;
@@ -69,18 +69,20 @@ export class Ctx {
         this.files = opts.files;
     }
     /**
-     * 平台下发的追踪上下文（run_id / workflow_id / node_id）。
+     * Tracing context supplied by the platform (run_id / workflow_id / node_id).
      *
-     * 非工作流调用（试调用、健康检查）没有这些值，返回空串——**调用方要把空串当
-     * 「没有重试语义」处理**，而不是当成一个恒定的键（那会把两次独立调用错误地去重）。
+     * Calls outside a workflow (console tests, health checks) have none of these and get "" back.
+     * **Treat "" as "no retry semantics"**, never as a constant key — doing the latter would
+     * deduplicate two independent calls into one.
      */
     trace(key) {
         return this.traceMap[key] ?? "";
     }
     /**
-     * 凭证按类型化形状读出。返回 Partial<T> 而不是 T —— 平台下发的是「这条凭证有哪些字段」，
-     * 生成的 Credential 里标必填的字段在运行时仍可能缺（凭证刚建、还没登录）。
-     * 假装它一定在，只会把一次 undefined 推迟到更远的地方炸。
+     * Read the credential into a typed shape. It returns Partial<T> rather than T: the platform sends
+     * whichever fields that credential row has, and a field the generated Credential marks required
+     * can still be missing at runtime (a freshly created credential, one that has not logged in yet).
+     * Pretending otherwise only moves the undefined further from where it will explode.
      */
     credentialAs() {
         return this.credential;
@@ -89,20 +91,21 @@ export class Ctx {
         if (f.data)
             return f.data;
         if (!this.files)
-            throw new Error("文件运行时未就绪");
+            throw new Error("file runtime not ready");
         return this.files.fetch(f);
     }
-    /** 产出一个文件：字节交回平台登记，返回可放进出参的引用。 */
+    /** Produce a file: hand the bytes back to the platform and get a reference for the output. */
     async upload(name, mime, data) {
         if (!this.files)
             return { name, mime, size: data.length, data };
         return this.files.store(name, mime, data);
     }
     /**
-     * 边读边传本地文件：内存占用恒为一个块（1 MiB），与文件大小无关。
+     * Stream a local file: memory stays at one chunk (1 MiB) regardless of file size.
      *
-     * 几百 MB 以上的东西（视频、压缩包、数据集）一律走它——upload() 要先把整个文件
-     * 读进内存，那会把插件进程撑爆，而症状是「大文件时容器莫名其妙被 OOM 杀掉」。
+     * Anything above a few hundred megabytes (video, archives, datasets) belongs here. upload() reads
+     * the whole file into memory first, and the symptom of that is a container mysteriously killed by
+     * the OOM reaper on large inputs.
      */
     async uploadFile(path, name, mime) {
         const { createReadStream, readFileSync } = await import("node:fs");

package/dist/src/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/src/webhook.d.ts

@@ -1,9 +1,12 @@
 /**
- * 平台代插件收 webhook：外部系统 → 平台 /hooks/{token} → __webhook__ 帧到这里（协议 §7b）。
+ * Webhooks relayed by the platform: upstream system -> platform /hooks/{token} -> a __webhook__
+ * frame lands here (protocol §7b).
  *
- * handler 的职责：用凭证里的 secret 验上游签名（各家算法不同，平台不懂上游、插件懂）→
- * 解析 body → ctx.trigger 推 typed 事件（走既有声明校验与平台去重）→ 返回响应
- * （GitLab 要 2xx、飞书 URL 校验要回 challenge，由 handler 决定）。
+ * What the handler is responsible for: verifying the upstream signature using the secret in the
+ * credential (every vendor signs differently — the platform does not know the upstream, the plugin
+ * does), parsing the body, pushing typed events with ctx.trigger (which reuses the declared-event
+ * check and the platform's deduplication), and deciding the response (GitLab wants a 2xx, Feishu's
+ * URL verification wants the challenge echoed back).
  */
 export interface WebhookFrame {
     method?: string;
@@ -12,27 +15,29 @@ export interface WebhookFrame {
     headers?: Record<string, string>;
     body_b64?: string;
 }
-/** 一次入站 webhook（平台已剥掉 Cookie 等平台侧头）。 */
+/** One inbound webhook (the platform has already stripped Cookie and other platform-side headers). */
 export declare class WebhookRequest {
     readonly method: string;
     readonly path: string;
     readonly query: string;
     readonly headers: Record<string, string>;
-    /** body 走 base64 保原始字节：HMAC 类验签必须逐字节一致，JSON 重编码会破坏签名。 */
+    /** The body travels as base64 to keep the exact bytes: HMAC-style verification has to see them
+     * byte for byte, and re-encoding the JSON would break the signature. */
     readonly body: Buffer;
     constructor(frame: WebhookFrame);
-    /** 大小写不敏感取头（HTTP 语义；X-Gitlab-Event 与 x-gitlab-event 都认）。 */
+    /** Case-insensitive header lookup (HTTP semantics: X-Gitlab-Event and x-gitlab-event both hit). */
     header(name: string): string;
-    /** body 按 JSON 解。解不开时抛错——上游发了坏 JSON 该是一次可见的失败。 */
+    /** Parse the body as JSON. Throws on bad input: malformed JSON upstream should fail visibly. */
     json<T = unknown>(): T;
 }
-/** 回给上游的应答。status=0 + error 表示处理失败（平台翻译成 5xx）。 */
+/** The reply sent back upstream. status=0 plus an error means the plugin failed to handle it (the
+ * platform translates that into a 5xx). */
 export interface WebhookResponse {
     status: number;
     headers?: Record<string, string>;
     body?: Buffer | string;
 }
 export declare function ok(): WebhookResponse;
-/** 要回 body 的场景（飞书 URL 校验的 challenge 这类）。 */
+/** For the cases that must return a body (Feishu's URL-verification challenge, say). */
 export declare function text(status: number, body: string): WebhookResponse;
 export declare function responseFrame(resp: WebhookResponse, events: number): Record<string, unknown>;

package/dist/src/webhook.js

@@ -1,17 +1,13 @@
-/**
- * 平台代插件收 webhook：外部系统 → 平台 /hooks/{token} → __webhook__ 帧到这里（协议 §7b）。
- *
- * handler 的职责：用凭证里的 secret 验上游签名（各家算法不同，平台不懂上游、插件懂）→
- * 解析 body → ctx.trigger 推 typed 事件（走既有声明校验与平台去重）→ 返回响应
- * （GitLab 要 2xx、飞书 URL 校验要回 challenge，由 handler 决定）。
- */
-/** 一次入站 webhook（平台已剥掉 Cookie 等平台侧头）。 */
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
+/** One inbound webhook (the platform has already stripped Cookie and other platform-side headers). */
 export class WebhookRequest {
     method;
     path;
     query;
     headers;
-    /** body 走 base64 保原始字节：HMAC 类验签必须逐字节一致，JSON 重编码会破坏签名。 */
+    /** The body travels as base64 to keep the exact bytes: HMAC-style verification has to see them
+     * byte for byte, and re-encoding the JSON would break the signature. */
     body;
     constructor(frame) {
         this.method = frame.method ?? "POST";
@@ -20,7 +16,7 @@ export class WebhookRequest {
         this.headers = frame.headers ?? {};
         this.body = Buffer.from(frame.body_b64 ?? "", "base64");
     }
-    /** 大小写不敏感取头（HTTP 语义；X-Gitlab-Event 与 x-gitlab-event 都认）。 */
+    /** Case-insensitive header lookup (HTTP semantics: X-Gitlab-Event and x-gitlab-event both hit). */
     header(name) {
         const lowered = name.toLowerCase();
         for (const [k, v] of Object.entries(this.headers)) {
@@ -29,7 +25,7 @@ export class WebhookRequest {
         }
         return "";
     }
-    /** body 按 JSON 解。解不开时抛错——上游发了坏 JSON 该是一次可见的失败。 */
+    /** Parse the body as JSON. Throws on bad input: malformed JSON upstream should fail visibly. */
     json() {
         return JSON.parse(this.body.toString("utf8"));
     }
@@ -37,7 +33,7 @@ export class WebhookRequest {
 export function ok() {
     return { status: 200 };
 }
-/** 要回 body 的场景（飞书 URL 校验的 challenge 这类）。 */
+/** For the cases that must return a body (Feishu's URL-verification challenge, say). */
 export function text(status, body) {
     return { status, body };
 }

package/dist/src/webhook.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,wCAAwC;AACxC,MAAM,OAAO,cAAc;IAChB,MAAM,CAAS;IACf,IAAI,CAAS;IACb,KAAK,CAAS;IACd,OAAO,CAAyB;IACzC,yDAAyD;IAChD,IAAI,CAAS;IAEtB,YAAY,KAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED,4DAA4D;IAC5D,MAAM,CAAC,IAAY;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO;gBAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,kDAAkD;IAClD,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAM,CAAC;IACrD,CAAC;CACF;AASD,MAAM,UAAU,EAAE;IAChB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACzB,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,IAAI,CAAC,MAAc,EAAE,IAAY;IAC/C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAqB,EAAE,MAAc;IACjE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAa,CAAC,CAAC;IACzF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI;QAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACjC,MAAM;KACP,CAAC;AACJ,CAAC"}
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/webhook.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAqBtC,sGAAsG;AACtG,MAAM,OAAO,cAAc;IAChB,MAAM,CAAS;IACf,IAAI,CAAS;IACb,KAAK,CAAS;IACd,OAAO,CAAyB;IACzC;4EACwE;IAC/D,IAAI,CAAS;IAEtB,YAAY,KAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED,mGAAmG;IACnG,MAAM,CAAC,IAAY;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO;gBAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,gGAAgG;IAChG,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAM,CAAC;IACrD,CAAC;CACF;AAUD,MAAM,UAAU,EAAE;IAChB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACzB,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,IAAI,CAAC,MAAc,EAAE,IAAY;IAC/C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAqB,EAAE,MAAc;IACjE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAa,CAAC,CAAC;IACzF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI;QAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACjC,MAAM;KACP,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sokel-dev/plugin-sdk",
-  "version": "0.3.0",
+  "version": "0.5.3",
   "description": "Sokel plugin SDK for Node.js — declare the contract in sokel.yaml, implement typed handlers.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sokel-dev/sokel-plugin-sdk/tree/main/sdk-node",