@triggerlink/sdk 0.4.8 → 0.4.9

package/dist/execx.d.ts

@@ -11,13 +11,16 @@ export interface OpError {
 }
 /** 应用 → 平台的执行指令（serve 序列化为响应）。 */
 export interface Opcode {
-    op: "StepComplete" | "StepError" | "RunComplete" | "RunError" | "Sleep" | "SendEvent";
+    op: "StepComplete" | "StepError" | "RunComplete" | "RunError" | "Sleep" | "SendEvent" | "WaitForEvent";
     id?: string;
     step_id?: string;
     output?: unknown;
     error?: OpError;
     until?: string;
     events?: OutgoingEvent[];
+    event?: string;
+    match?: string;
+    timeout?: string;
 }
 /** step.sendEvent 待扇出的事件（id/ts 缺省由平台补全，id 缺省为确定性派生）。 */
 export interface OutgoingEvent {

package/dist/function.d.ts

@@ -6,6 +6,15 @@ export interface EventPayload<T = unknown> {
     data: T;
     ts: string;
 }
+/** step.waitForEvent 命中后返回的事件（与 EventPayload 同构）。 */
+export type TriggerLinkEvent<T = unknown> = EventPayload<T>;
+/** cancelOn 取消规则（FR-4.9）：event 到达且 match 命中时，平台取消该函数的在途 run。 */
+export interface CancelOnRule {
+    /** 触发取消的事件名 */
+    event: string;
+    /** 可选 expr 表达式，留空 = 该事件到达即取消；环境：data=到达事件 data，event=本 run 触发事件 {name, data} */
+    match?: string;
+}
 /** 传给用户 handler 的上下文。 */
 export interface HandlerContext<T = unknown> {
     event: EventPayload<T>;
@@ -20,9 +29,13 @@ export interface FunctionOpts {
     event: string;
     /** 重试上限；0/缺省 = 平台默认（4） */
     retries?: number;
+    /** 取消规则，随 manifest 上报为 cancel_on */
+    cancelOn?: CancelOnRule[];
 }
 export interface TriggerFunction<T = unknown> {
-    readonly opts: Required<FunctionOpts>;
+    readonly opts: FunctionOpts & {
+        retries: number;
+    };
     readonly handler: (ctx: HandlerContext<T>) => Promise<unknown>;
 }
 /** 定义一个 durable 函数。副作用必须放进 step.run（协议第 6 节约束）。 */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createClient, type Client, type ClientOptions, type SendEventInput, type SendResult, type RegisterOptions, } from "./client.js";
-export { createFunction, type TriggerFunction, type FunctionOpts, type HandlerContext, type EventPayload, } from "./function.js";
+export { createFunction, type TriggerFunction, type FunctionOpts, type HandlerContext, type EventPayload, type TriggerLinkEvent, type CancelOnRule, } from "./function.js";
 export { serve, sdkVersion, type ServeOptions } from "./serve.js";
 export { StepInterrupt, type Opcode, type StepState, type OutgoingEvent } from "./execx.js";
-export type { StepTool } from "./step.js";
+export type { StepTool, WaitForEventOpts } from "./step.js";

package/dist/serve.js

@@ -22,6 +22,9 @@ export function serve(opts) {
                 id: f.opts.id,
                 event: f.opts.event,
                 retries: f.opts.retries,
+                ...(f.opts.cancelOn?.length
+                    ? { cancel_on: f.opts.cancelOn.map((c) => ({ event: c.event, match: c.match })) }
+                    : {}),
             })),
         });
     }

package/dist/step.d.ts

@@ -1,4 +1,14 @@
 import { ExecCtx, type OutgoingEvent } from "./execx.js";
+import type { TriggerLinkEvent } from "./function.js";
+/** step.waitForEvent 的配置。 */
+export interface WaitForEventOpts {
+    /** 等待的事件名（必填） */
+    event: string;
+    /** 可选 expr 表达式；求值环境：data=到达事件 data，event=本 run 触发事件 {name, data} */
+    match?: string;
+    /** 可选超时：Go duration 字符串（如 "168h"）或毫秒数（1500 → "1.5s"）；超时后返回 null */
+    timeout?: string | number;
+}
 /** handler 内可用的 step 工具。 */
 export interface StepTool {
     /**
@@ -19,6 +29,13 @@ export interface StepTool {
      * memo 语义同 run——恢复重入时直接返回已发事件 ID 列表，不会重复发送。
      */
     sendEvent(id: string, events: OutgoingEvent | OutgoingEvent[]): Promise<string[]>;
+    /**
+     * 挂起当前 run 直至匹配事件到达或超时（协议 5.7 / FR-2.6）：
+     * 事件命中 → 返回该事件；超时 → 返回 null（超时分支）。
+     * 与 sleep 同为挂起原语（恢复重入时 memo 命中直接返回），但唤醒由平台在
+     * 事件路由命中/超时扫描时驱动，挂起期间零占用。
+     */
+    waitForEvent(id: string, opts: WaitForEventOpts): Promise<TriggerLinkEvent | null>;
 }
 /** 为一次函数调用构造 step 工具。 */
 export declare function createStepTool(ec: ExecCtx): StepTool;

package/dist/step.js

@@ -45,8 +45,34 @@ export function createStepTool(ec) {
                 throw new Error(`step.sendEvent "${id}": no events`);
             throw new StepInterrupt({ op: "SendEvent", id: h, step_id: id, events: list });
         },
+        async waitForEvent(id, opts) {
+            const h = ec.nextHash(id);
+            const memo = ec.steps[h];
+            if (memo && memo.status === "completed") {
+                if (memo.output == null)
+                    return null; // 超时分支：平台以 output=JSON null 完成
+                return memo.output;
+            }
+            if (!opts.event)
+                throw new Error(`step.waitForEvent "${id}": event is required`);
+            throw new StepInterrupt({
+                op: "WaitForEvent",
+                id: h,
+                step_id: id,
+                event: opts.event,
+                match: opts.match,
+                timeout: typeof opts.timeout === "number" ? msToGoDuration(opts.timeout) : opts.timeout,
+            });
+        },
     };
 }
+/** 毫秒 → Go duration 字符串（协议要求 timeout 为 Go duration，如 1500 → "1.5s"）。 */
+function msToGoDuration(ms) {
+    if (!Number.isFinite(ms) || ms <= 0) {
+        throw new Error(`step.waitForEvent: invalid timeout ${ms}`);
+    }
+    return `${ms / 1000}s`;
+}
 export function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triggerlink/sdk",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "TriggerLink TypeScript SDK: durable, crash-recoverable functions for Next.js / Node.js",
   "keywords": [
     "triggerlink",