@triggerlink/sdk 0.4.9 → 0.5.1

package/dist/function.d.ts

@@ -22,15 +22,39 @@ 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 级超时（FR-4.3），随 manifest 上报为 timeout（Go duration 字符串或毫秒数，
+     * 如 "5m" 或 300000）。run 从创建起超过该时长仍在 Queued/Running，平台置 Failed
+     * 并发 triggerlink/run.failed 事件——配置了 onFailure 的函数会因此触发。缺省 = 不限时。
+     */
+    timeout?: string | number;
+    /**
+     * 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: FunctionOpts & {

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, type TriggerLinkEvent, type CancelOnRule, } 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, WaitForEventOpts } from "./step.js";

package/dist/serve.js

@@ -1,5 +1,5 @@
 import { ExecCtx, StepInterrupt } from "./execx.js";
-import { createStepTool, errMessage } from "./step.js";
+import { createStepTool, errMessage, msToGoDuration } from "./step.js";
 import { verifySignature } from "./sign.js";
 export const sdkVersion = "triggerlink-ts/0.4.6";
 export const SIGNATURE_HEADER = "x-triggerlink-signature";
@@ -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,10 +34,19 @@ 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 })) }
                     : {}),
+                ...(f.opts.timeout
+                    ? {
+                        timeout: typeof f.opts.timeout === "number"
+                            ? msToGoDuration(f.opts.timeout, "createFunction")
+                            : f.opts.timeout,
+                    }
+                    : {}),
             })),
         });
     }

package/dist/step.d.ts

@@ -39,4 +39,6 @@ export interface StepTool {
 }
 /** 为一次函数调用构造 step 工具。 */
 export declare function createStepTool(ec: ExecCtx): StepTool;
+/** 毫秒 → Go duration 字符串（协议要求 timeout 为 Go duration，如 1500 → "1.5s"）。 */
+export declare function msToGoDuration(ms: number, what?: string): string;
 export declare function errMessage(err: unknown): string;

package/dist/step.js

@@ -67,9 +67,9 @@ export function createStepTool(ec) {
     };
 }
 /** 毫秒 → Go duration 字符串（协议要求 timeout 为 Go duration，如 1500 → "1.5s"）。 */
-function msToGoDuration(ms) {
+export function msToGoDuration(ms, what = "step.waitForEvent") {
     if (!Number.isFinite(ms) || ms <= 0) {
-        throw new Error(`step.waitForEvent: invalid timeout ${ms}`);
+        throw new Error(`${what}: invalid timeout ${ms}`);
     }
     return `${ms / 1000}s`;
 }

package/package.json

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