@sokel-dev/plugin-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The Sokel Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,95 @@
+# Sokel Plugin SDK — Node.js / TypeScript
+
+用 TypeScript 写 [Sokel](https://github.com/sokel-dev) 插件。契约写在 `sokel.yaml` 里（语言中立），
+`sokel-gen` 把它生成成 TS 接口与类型化的注册口；SDK 负责注册、传输、凭证、文件、心跳与重连。
+
+```ts
+onIssuesList(p, async (ctx, in_) => {
+  const issues = await client.listIssues(in_.project, in_.state);
+  return { issues, count: issues.length };
+});
+```
+
+`in_.project` 拼错是编译错误，不是线上的一次失败调用——代码里没有任何 `any`。
+
+## 装
+
+```bash
+npm install @sokel-dev/plugin-sdk
+go install github.com/sokel-dev/sokel-plugin-sdk/cmd/sokel-gen@latest   # 生成器
+```
+
+`sokel-gen` 是个单文件二进制（Go 写的），只在**生成时**用到；跑插件时不需要它。
+
+## 四步
+
+```bash
+sokel-gen init -lang ts ./my-plugin
+cd my-plugin
+npm install
+sokel-gen generate .     # sokel.yaml → src/sokel.gen.ts
+npm run build && npm start
+```
+
+1. **声明** —— `sokel.yaml`：操作、事件、凭证、认证方式。格式见 [docs/manifest.md](../docs/manifest.md)。
+2. **生成** —— `sokel-gen generate .` 产出 `src/sokel.gen.ts`：每个操作一对 `XxxIn` / `XxxOut` 接口
+   和一个 `onXxx(p, fn)`；每个事件一个 payload 接口和一个 `triggerXxx(ctx, eventId, payload)`。
+3. **实现** —— handler 签名完全具体，返回值可以是对象也可以是 Promise。
+4. **连接** —— `await p.run()`。插件**出站**连平台：无入站端口、无公网 IP、无防火墙洞。
+
+## 为什么不是 zod
+
+zod schema 是运行时对象：用它声明契约意味着「契约只有跑起来才知道」，而且每种语言都得
+自己解释一遍那套 DSL。声明留在 `sokel.yaml`，TS 这边只要类型——类型在编译期，运行时零开销。
+
+## 能力一览
+
+| 要做的事 | 怎么写 |
+|---|---|
+| 读凭证 | `ctx.credentialAs<Credential>()` |
+| 取入参文件的字节 | `await ctx.fetch(in_.file)` |
+| 产出文件 | `await ctx.upload(name, mime, bytes)` → 放进出参 |
+| 流式产出 | `out.text(...)` 逐帧给人看，`out.vars({...})` 给下游 |
+| 推事件 | `await triggerMessage(ctx, eventId, {...})` |
+| 常驻事件源 | `p.registerSource(id, label, fn)`，循环里判 `ctx.stopped` |
+| 平台代收 webhook | `p.registerWebhook(fn)`，返回 `ok()` / `text(401, "...")` |
+| 协作式认证 | `p.registerAuth({ start, poll, submit })` |
+| 会话型凭证刷新 | `await ctx.updateCredential({ session: "…" })` |
+| 自报运行态 | `ctx.reportStatus("auth_required", "…")` |
+
+## 配置
+
+SDK 读 `SOKEL_` 前缀的环境变量：
+
+| 变量 | 必填 | 含义 |
+|---|---|---|
+| `SOKEL_ENDPOINT` | 是 | `nats://broker:4222`，或 `https://` 平台地址（经 `/connect-info` 发现 broker） |
+| `SOKEL_TOKEN` | 是 | 接入组 token（`skp_…`），平台据此认「插件 + 工作空间」 |
+| `SOKEL_NATS_TOKEN` | 否 | broker 的传输层鉴权 |
+| `SOKEL_NATS_CA` | 否 | `tls://` broker 的自定义 CA |
+| `SOKEL_INSTANCE_ID` | 否 | 固定副本身份（默认按 token 指纹落盘复用） |
+| `SOKEL_REGION` | 否 | 副本的地域标注 |
+
+凭证从不由插件存储：平台随每次调用把解析后的字段下发下来。
+
+## 例子
+
+[`examples/kitchen-sink`](../examples/kitchen-sink) 覆盖了全部形态——每种字段、文件、流式、
+事件、webhook、协作式认证各一份，Node 与 Python 实现的是同一份声明。
+
+```bash
+cd examples/kitchen-sink/node
+npm install && npm run build
+SOKEL_ENDPOINT=nats://localhost:4222 SOKEL_TOKEN=skp_xxx npm start
+```
+
+## 开发本 SDK
+
+```bash
+pnpm install
+pnpm test        # tsc + node --test
+```
+
+## License
+
+Apache-2.0.

package/dist/src/auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 协作式凭证认证：有些凭证没法让人填——扫码、验证码回填、OAuth 同意页。
+ *
+ * 面板点「登录」→ start 拿挑战 →（扫码 / 回填）→ 2s 轮询 poll → confirmed。
+ *
+ * 形态写在 sokel.yaml 的 credential.auth 里（声明式），处理器挂在保留操作 id
+ * auth.start / auth.poll / auth.submit 上——**不要**自己注册叫 auth_start 的业务操作：
+ * 那三个名字从来不是保留字，任何插件的同名业务操作都会让面板的按钮凭空出现。
+ */
+import type { Ctx } from "./runtime.js";
+export declare const PENDING = "pending";
+export declare const SCANNED = "scanned";
+export declare const CONFIRMED = "confirmed";
+export declare const EXPIRED = "expired";
+/** start 交出的挑战。面板按 kind 渲染：qr 画二维码，input 显示 prompt 与输入框。 */
+export interface AuthChallenge {
+    authId?: string;
+    kind?: "qr" | "input";
+    /** data-uri 形态的二维码图片。 */
+    qrImage?: string;
+    prompt?: string;
+    expiresIn?: number;
+}
+/** poll 的结果。session 只在 confirmed 时带上——中途带出去等于让平台反复覆写凭证行。 */
+export interface AuthState {
+    status: string;
+    session?: Record<string, unknown>;
+}
+export interface AuthHandlers {
+    start?: (ctx: Ctx) => Promise<AuthChallenge> | AuthChallenge;
+    poll?: (ctx: Ctx, authId: string) => Promise<AuthState> | AuthState;
+    submit?: (ctx: Ctx, authId: string, input: string) => Promise<void> | void;
+}

package/dist/src/auth.js

@@ -0,0 +1,14 @@
+/**
+ * 协作式凭证认证：有些凭证没法让人填——扫码、验证码回填、OAuth 同意页。
+ *
+ * 面板点「登录」→ start 拿挑战 →（扫码 / 回填）→ 2s 轮询 poll → confirmed。
+ *
+ * 形态写在 sokel.yaml 的 credential.auth 里（声明式），处理器挂在保留操作 id
+ * auth.start / auth.poll / auth.submit 上——**不要**自己注册叫 auth_start 的业务操作：
+ * 那三个名字从来不是保留字，任何插件的同名业务操作都会让面板的按钮凭空出现。
+ */
+export const PENDING = "pending";
+export const SCANNED = "scanned";
+export const CONFIRMED = "confirmed";
+export const EXPIRED = "expired";
+//# sourceMappingURL=auth.js.map

package/dist/src/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC"}

package/dist/src/contract.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 契约的运行时视图（线协议 §5）。
+ *
+ * 契约本身是**数据**：`sokel-gen` 从 sokel.yaml 生成一份 CONTRACT 常量，运行时只是查它、上报它。
+ * 所以这里不重新定义一套 Field 校验器——那会变成契约的第二份定义，而两份定义迟早会漂。
+ */
+/** 一个入/出参字段（协议 §5 的 Field）。这里只声明形状，不做校验——校验在 sokel-gen。 */
+export interface Field {
+    name: string;
+    label?: string;
+    type: string;
+    types?: string[];
+    required?: boolean;
+    default?: unknown;
+    desc?: string;
+    options?: Array<string | {
+        value: string;
+        label?: string;
+    }>;
+    fields?: Field[];
+    valueType?: Field;
+    itemType?: string;
+    goType?: string;
+    opaque?: boolean;
+    oneOf?: Array<{
+        name: string;
+        label?: string;
+        type: string;
+        fields?: Field[];
+    }>;
+}
+export interface OperationSpec {
+    id: string;
+    label?: string;
+    desc?: string;
+    stream?: boolean;
+    internal?: boolean;
+    timeoutSec?: number;
+    inputs: Field[];
+    outputs: Field[];
+}
+export interface EventSpec {
+    id: string;
+    label?: string;
+    desc?: string;
+    fields: Field[];
+}
+export interface AuthFlowSpec {
+    kind: "qr" | "input" | "oauth";
+    steps?: string[];
+}
+/** 生成物 CONTRACT 的形状。键名与注册载荷（协议 §3）同名，直接上报，不做转换。 */
+export interface ContractData {
+    name?: string;
+    label?: string;
+    desc?: string;
+    version?: string;
+    operations: OperationSpec[];
+    credential_schema?: Field[];
+    events?: EventSpec[];
+    events_common?: Field[];
+    auth_flow?: AuthFlowSpec;
+    oauth?: {
+        provider: string;
+        scopes?: string[];
+    };
+    capabilities?: Record<string, boolean>;
+    doc?: string;
+    doc_url?: string;
+}
+/** 保留操作 id（认证流）。带点号，业务 id 产生不出来（业务 id 限定 ^[a-z][a-z0-9_]*$）。 */
+export declare const OP_AUTH_START = "auth.start";
+export declare const OP_AUTH_POLL = "auth.poll";
+export declare const OP_AUTH_SUBMIT = "auth.submit";
+/** 平台代收 webhook 的特殊操作名（复用调用帧，见协议 §7b）。 */
+export declare const OP_WEBHOOK = "__webhook__";
+/** 能力位：注册了 webhook 处理器就是支持，不靠作者手动声明。 */
+export declare const CAP_WEBHOOK = "webhook";
+export declare class Contract {
+    readonly data: ContractData;
+    constructor(data: ContractData);
+    operations(): OperationSpec[];
+    operation(id: string): OperationSpec | undefined;
+    isStream(id: string): boolean;
+    eventIds(): string[];
+    /** 契约部分的注册载荷。空值一律省略（协议：新字段一律 optional）。 */
+    payload(): Record<string, unknown>;
+}

package/dist/src/contract.js

@@ -0,0 +1,55 @@
+/**
+ * 契约的运行时视图（线协议 §5）。
+ *
+ * 契约本身是**数据**：`sokel-gen` 从 sokel.yaml 生成一份 CONTRACT 常量，运行时只是查它、上报它。
+ * 所以这里不重新定义一套 Field 校验器——那会变成契约的第二份定义，而两份定义迟早会漂。
+ */
+/** 保留操作 id（认证流）。带点号，业务 id 产生不出来（业务 id 限定 ^[a-z][a-z0-9_]*$）。 */
+export const OP_AUTH_START = "auth.start";
+export const OP_AUTH_POLL = "auth.poll";
+export const OP_AUTH_SUBMIT = "auth.submit";
+/** 平台代收 webhook 的特殊操作名（复用调用帧，见协议 §7b）。 */
+export const OP_WEBHOOK = "__webhook__";
+/** 能力位：注册了 webhook 处理器就是支持，不靠作者手动声明。 */
+export const CAP_WEBHOOK = "webhook";
+export class Contract {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    operations() {
+        return this.data.operations ?? [];
+    }
+    operation(id) {
+        return this.operations().find((op) => op.id === id);
+    }
+    isStream(id) {
+        return this.operation(id)?.stream === true;
+    }
+    eventIds() {
+        return (this.data.events ?? []).map((e) => e.id);
+    }
+    /** 契约部分的注册载荷。空值一律省略（协议：新字段一律 optional）。 */
+    payload() {
+        const out = { operations: this.operations() };
+        const d = this.data;
+        if (d.credential_schema?.length)
+            out.credential_schema = d.credential_schema;
+        if (d.events?.length)
+            out.events = d.events;
+        if (d.events_common?.length)
+            out.events_common = d.events_common;
+        if (d.auth_flow)
+            out.auth_flow = d.auth_flow;
+        if (d.oauth)
+            out.oauth = d.oauth;
+        if (d.capabilities && Object.keys(d.capabilities).length)
+            out.capabilities = d.capabilities;
+        if (d.doc)
+            out.doc = d.doc;
+        if (d.doc_url)
+            out.doc_url = d.doc_url;
+        return out;
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/src/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4DH,gEAAgE;AAChE,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C,0CAA0C;AAC1C,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC;AAExC,wCAAwC;AACxC,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC,MAAM,OAAO,QAAQ;IACE;IAArB,YAAqB,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAE3C,UAAU;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;IACpC,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,QAAQ,CAAC,EAAU;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,2CAA2C;IAC3C,OAAO;QACL,MAAM,GAAG,GAA4B,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACvE,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACpB,IAAI,CAAC,CAAC,iBAAiB,EAAE,MAAM;YAAE,GAAG,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB,CAAC;QAC7E,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM;YAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QAC5C,IAAI,CAAC,CAAC,aAAa,EAAE,MAAM;YAAE,GAAG,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;QACjE,IAAI,CAAC,CAAC,SAAS;YAAE,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;QAC7C,IAAI,CAAC,CAAC,KAAK;YAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACjC,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;QAC5F,IAAI,CAAC,CAAC,GAAG;YAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;QAC3B,IAAI,CAAC,CAAC,OAAO;YAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QACvC,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/src/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 插件侧环境变量的统一读法：把 SOKEL_ 前缀收在一处（对齐 Go 侧 pluginenv）。
+ *
+ * 没有第二个前缀的兼容层——认第二个前缀省下的是一次重新部署，换来的是一个没人敢摘的包袱。
+ */
+/** 读 SOKEL_<name>。name 不带前缀，如 env("TOKEN")。 */
+export declare function env(name: string): string;
+export declare function envOr(name: string, fallback: string): string;

package/dist/src/env.js

@@ -0,0 +1,14 @@
+/**
+ * 插件侧环境变量的统一读法：把 SOKEL_ 前缀收在一处（对齐 Go 侧 pluginenv）。
+ *
+ * 没有第二个前缀的兼容层——认第二个前缀省下的是一次重新部署，换来的是一个没人敢摘的包袱。
+ */
+const PREFIX = "SOKEL_";
+/** 读 SOKEL_<name>。name 不带前缀，如 env("TOKEN")。 */
+export function env(name) {
+    return (process.env[PREFIX + name] ?? "").trim();
+}
+export function envOr(name, fallback) {
+    return env(name) || fallback;
+}
+//# sourceMappingURL=env.js.map

package/dist/src/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB,+CAA+C;AAC/C,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,QAAgB;IAClD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;AAC/B,CAAC"}

package/dist/src/events.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 事件源：插件主动把外部事件推给平台起 workflow（协议 §7）。
+ *
+ * 与操作的区别：操作是 request/reply（平台调插件），事件是 fire-and-forget（插件推平台）。
+ *
+ * 多 bot 单实例（协议 v1.3）：平台每次注册/心跳下发「分配给本副本的凭证子集」，
+ * supervisor 按它 reconcile —— 每个凭证一套源实例，凭证被移除就取消，字段变了就重启。
+ */
+import type { FileRuntime, SokelFile } from "./runtime.js";
+export declare const TRIGGER_SUBJECT = "sokel.trigger";
+export declare const CREDENTIAL_UPDATE_SUBJECT = "sokel.credential.update";
+/** 注册回包 credentials 列表项 —— 分配给本副本的一个 bot 身份。 */
+export declare class CredEntry {
+    readonly id: string;
+    readonly fields: Record<string, string>;
+    constructor(id?: string, fields?: Record<string, string>);
+    /** 字段的稳定签名：reconcile 据此判定「字段变更 → 重启该源实例」。 */
+    sig(): string;
+}
+export interface SourceState {
+    source_id: string;
+    credential_id?: string;
+    status: string;
+    error?: string;
+    since: string;
+}
+/** 源实例运行态（源 × 凭证）。随注册/心跳上报，面板据此展示每个 bot。 */
+export declare class StateBoard {
+    private readonly now;
+    private readonly m;
+    constructor(now?: () => string);
+    set(sourceId: string, credId: string, status: string, error?: string): void;
+    /**
+     * 只在该实例仍是 running 时改写。
+     *
+     * 源自报过状态（如 auth_required）之后正常返回，收尾时不该把那句话盖掉——
+     * 盖掉之后面板上只剩一个「已退出」，而「为什么退出」正是要看的那一半。
+     */
+    setIfRunning(sourceId: string, credId: string, status: string, error?: string): void;
+    removeCred(credId: string): void;
+    snapshot(): SourceState[];
+}
+export type Publish = (subject: string, data: Uint8Array) => void | Promise<void>;
+/** 常驻事件源 / webhook 的上下文：推事件、读凭证、回写凭证、上传附件、自报状态。 */
+export declare class SourceCtx {
+    readonly credential: Record<string, string>;
+    readonly credentialId: string;
+    readonly sourceId: string;
+    /** stopped：该源实例被 reconcile 停止时置真。长轮询循环 while (!ctx.stopped)。 */
+    stopped: boolean;
+    private readonly token;
+    private readonly publish;
+    private readonly validEvents;
+    private readonly board?;
+    private readonly files?;
+    constructor(opts: {
+        token: string;
+        publish: Publish;
+        validEvents?: string[];
+        credential?: Record<string, string>;
+        credentialId?: string;
+        sourceId?: string;
+        board?: StateBoard;
+        files?: FileRuntime;
+    });
+    /** 凭证按类型化形状读出（与操作侧 Ctx.credentialAs 同义）。 */
+    credentialAs<T extends object>(): Partial<T>;
+    /**
+     * 推一条事件（fire-and-forget）。
+     *
+     * event 必须是已声明的事件 id —— 拼错在这里当场报错，而不是变成一条平台侧无人认领的
+     * 消息（那种失败没有任何症状：插件日志正常，工作流就是不起）。
+     * eventId 是幂等键，平台按 (plugin, event, eventId) 去重。
+     */
+    trigger(event: string, eventId: string, payload: unknown): Promise<void>;
+    /**
+     * 把 patch 回写到本实例绑定的平台凭证（会话型凭证运行中刷新用）。
+     * 平台是唯一凭证存储方，插件本地从不落地凭证。
+     */
+    updateCredential(patch: Record<string, string>): Promise<void>;
+    /** 自报运行态（如 session 失效 → auth_required），随心跳上报，面板亮「待登录」。 */
+    reportStatus(status: string, msg?: string): void;
+    upload(name: string, mime: string, data: Uint8Array): Promise<SokelFile>;
+    fetch(f: SokelFile): Promise<Uint8Array>;
+}
+/** 一个常驻事件源。fn 在 SDK 起的任务里跑，内部用 ctx.trigger 推事件。 */
+export interface Source {
+    id: string;
+    label: string;
+    fn: (ctx: SourceCtx) => Promise<void>;
+}
+/** per-credential 源实例监督器：按平台下发的凭证集合起停/重启。 */
+export declare class SourceSupervisor {
+    private readonly start;
+    private readonly running;
+    constructor(start: (c: CredEntry) => () => void);
+    reconcile(desired: CredEntry[]): void;
+    stopAll(): void;
+}
+/** 空（无凭证插件）→ 一个空凭证裸实例，与有凭证时同一条代码路径。 */
+export declare function desiredSourceCreds(creds: CredEntry[]): CredEntry[];