@triggerlink/sdk 0.4.8 → 0.5.0

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>;
@@ -13,16 +22,38 @@ export interface HandlerContext<T = unknown> {
     runId: string;
     attempt: number;
 }
+/** triggerlink/run.failed 内部事件的 data（FR-2.11），即 onFailure handler 的 event.data。 */
+export interface RunFailedEventData {
+    run_id: string;
+    function_id: string;
+    error: string;
+    /** 触发该 run 的原始事件 */
+    event: EventPayload;
+}
 export interface FunctionOpts {
     /** 稳定标识，改名会丢历史 memo 关联 */
     id: string;
-    /** 订阅的事件名 */
-    event: string;
+    /** 订阅的事件名；纯 cron 函数可省略（event/cron 至少其一） */
+    event?: string;
+    /** 事件触发 match 表达式（FR-3.1），expr 语法，环境只含 data（= 事件 data） */
+    match?: string;
+    /** 标准 5 字段 cron（分 时 日 月 周），UTC */
+    cron?: string;
     /** 重试上限；0/缺省 = 平台默认（4） */
     retries?: number;
+    /** 取消规则，随 manifest 上报为 cancel_on */
+    cancelOn?: CancelOnRule[];
+    /**
+     * run 进入 Failed 终态时的处理器（FR-2.11）。serve 时注册隐式函数 <id>/on-failure，
+     * 订阅内部事件 triggerlink/run.failed（match 按 function_id 过滤），handler 内可用全部 step 原语。
+     * onFailure 自身失败不会递归触发。
+     */
+    onFailure?: (ctx: HandlerContext<RunFailedEventData>) => Promise<unknown>;
 }
 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/function.js

@@ -2,7 +2,8 @@
 export function createFunction(opts, handler) {
     if (!opts.id)
         throw new Error("createFunction: id is required");
-    if (!opts.event)
-        throw new Error("createFunction: event is required");
+    if (!opts.event && !opts.cron) {
+        throw new Error("createFunction: event or cron is required"); // 纯 cron 函数无事件订阅
+    }
     return { opts: { retries: 0, ...opts }, handler };
 }

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, type RunFailedEventData, } 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

@@ -9,8 +9,21 @@ function json(data, status = 200) {
 }
 export function serve(opts) {
     const byID = new Map();
-    for (const fn of opts.functions)
+    for (const fn of opts.functions) {
         byID.set(fn.opts.id, fn);
+        if (fn.opts.onFailure) {
+            // FR-2.11：注册隐式函数，订阅 run 失败内部事件并按 function_id 过滤
+            byID.set(`${fn.opts.id}/on-failure`, {
+                opts: {
+                    id: `${fn.opts.id}/on-failure`,
+                    event: "triggerlink/run.failed",
+                    match: `data.function_id == '${fn.opts.id}'`,
+                    retries: 0,
+                },
+                handler: fn.opts.onFailure,
+            });
+        }
+    }
     async function GET(req) {
         if (!verifySignature(opts.client.signingKey, req.headers.get(SIGNATURE_HEADER), new Uint8Array(0))) {
             return json({ error: "unauthorized" }, 401);
@@ -21,7 +34,12 @@ export function serve(opts) {
             functions: [...byID.values()].map((f) => ({
                 id: f.opts.id,
                 event: f.opts.event,
+                ...(f.opts.match ? { match: f.opts.match } : {}),
+                ...(f.opts.cron ? { cron: f.opts.cron } : {}),
                 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.5.0",
   "description": "TriggerLink TypeScript SDK: durable, crash-recoverable functions for Next.js / Node.js",
   "keywords": [
     "triggerlink",