@triggerlink/sdk 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bearalise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @triggerlink/sdk — TypeScript SDK (M0 prototype)
+
+Lets Next.js / Node.js applications integrate with the TriggerLink platform using an
+Inngest-style DX. See the protocol spec at
+[`docs/protocol.md`](../docs/protocol.md). Currently supports the `step.run`,
+`step.sleep` / `step.sleepUntil`, and `step.sendEvent` primitives.
+
+## Integrating with Next.js (App Router)
+
+```bash
+npm install @triggerlink/sdk
+```
+
+```ts
+// app/api/triggerlink/route.ts
+import { createClient, createFunction, serve } from "@triggerlink/sdk";
+
+export const runtime = "nodejs";     // requires node:crypto and a longer execution limit
+export const maxDuration = 300;      // a single step must fit within the function limit (platform callback timeout is 5 minutes)
+
+const client = createClient({
+  id: "web",
+  signingKey: process.env.TRIGGERLINK_SIGNING_KEY!, // must match the platform's -signing-key
+});
+
+const fulfillOrder = createFunction(
+  { id: "fulfill-order", event: "order/paid" },
+  async ({ event, step }) => {
+    const { order_id } = event.data as { order_id: string };
+
+    // One side effect per step: on retry/crash recovery, completed steps are injected from memo and not re-run
+    const tracking = await step.run("create-shipment", () =>
+      logistics.createShipment(order_id),
+    );
+    await step.run("send-sms", () => sms.send(order_id, tracking));
+
+    return { tracking };
+  },
+);
+
+export const { GET, POST } = serve({ client, functions: [fulfillOrder] });
+```
+
+Platform-side registration (pick one):
+
+```bash
+# Platform-side static introspection: point -app at the app's serve URL at startup
+triggerlink -event-key ... -signing-key ... \
+  -app https://your-app.vercel.app/api/triggerlink
+```
+
+```ts
+// Or app-side self-registration (reversed direction): call once after startup, retries in the background, does not block startup
+client.register("http://localhost:3000/api/triggerlink"); // requires eventKey
+```
+
+Note: for local development, point the serve URL at `http://localhost:3000/api/triggerlink`; after changing functions in the app, call `POST /api/v1/apps/sync {"url":"..."}` to sync — no platform restart needed.
+
+## Constraints (same as the Go SDK; see protocol section 6)
+
+- Side effects must go inside `step.run`; the function is re-invoked from the start on every callback, so code outside steps runs repeatedly;
+- The step call sequence must be deterministic: branches/loops may only depend on event data and the outputs of completed steps;
+- A single step's duration must be shorter than both the deployment platform's function limit and the platform callback timeout (5 minutes by default).
+
+## Sending events (any TS code, modeled after Inngest's `inngest.send`)
+
+```ts
+const client = createClient({
+  id: "web",
+  signingKey: process.env.TRIGGERLINK_SIGNING_KEY!,
+  eventKey: process.env.TRIGGERLINK_EVENT_KEY!,   // required for send / register
+  baseUrl: process.env.TRIGGERLINK_BASE_URL,      // defaults to http://localhost:8288
+});
+
+// Single event; id is an idempotency key, safe to retry (generated by the platform if omitted)
+await client.send({
+  id: `order-${orderId}-paid`,
+  name: "order/paid",
+  data: { order_id: orderId },
+});
+
+// Or a batch
+await client.send([{ name: "x/y" }, { name: "x/z", data: { n: 1 } }]);
+```
+
+## Development
+
+```bash
+npm install
+npm test        # tsc build + node:test (simulates the platform's three-callback progression / memo injection / signature verification / error paths)
+npm run build   # outputs dist/ (ESM + .d.ts)
+```

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+export interface ClientOptions {
+    /** 应用标识，如 "web"，出现在内省清单中 */
+    id: string;
+    /** 与平台 -signing-key 共享的签名密钥 */
+    signingKey: string;
+    /** 与平台 -event-key 一致；send / register 需要 */
+    eventKey?: string;
+    /** 平台地址；send / register 需要，缺省 "http://localhost:8288" */
+    baseUrl?: string;
+}
+/** send 的入参事件（协议第 9 节）。id 缺省平台生成；提供则按 ID 幂等去重。 */
+export interface SendEventInput<T = unknown> {
+    id?: string;
+    name: string;
+    data?: T;
+    ts?: string;
+}
+export interface SendResult {
+    ids: string[];
+    status: number;
+}
+export interface RegisterOptions {
+    /** 重试间隔毫秒，缺省 2000 */
+    intervalMs?: number;
+    /** 最大尝试次数，缺省 150（≈5 分钟，覆盖平台晚于应用启动的场景） */
+    attempts?: number;
+}
+export interface Client {
+    readonly id: string;
+    readonly signingKey: string;
+    /** 发送单个事件或事件数组到平台（仿 Inngest `inngest.send`）。 */
+    send<T = unknown>(events: SendEventInput<T> | SendEventInput<T>[]): Promise<SendResult>;
+    /**
+     * 向平台管理 API 自注册本应用（POST /api/v1/apps），等价于平台 -app 静态内省的反向操作。
+     * 平台会为内省回调本应用的 serve URL，因此需要在应用可对外服务之后调用；
+     * 后台异步重试，不阻塞启动。等价于重复调用可兼作函数变更后的 sync。
+     */
+    register(serveUrl: string, opts?: RegisterOptions): void;
+}
+export declare function createClient(opts: ClientOptions): Client;

package/dist/client.js

@@ -0,0 +1,67 @@
+export function createClient(opts) {
+    if (!opts.id)
+        throw new Error("createClient: id is required");
+    if (!opts.signingKey)
+        throw new Error("createClient: signingKey is required");
+    const baseUrl = (opts.baseUrl ?? "http://localhost:8288").replace(/\/+$/, "");
+    async function send(events) {
+        if (!opts.eventKey)
+            throw new Error("client.send: eventKey is required (createClient 时传入)");
+        const list = Array.isArray(events) ? events : [events];
+        if (list.length === 0)
+            throw new Error("client.send: events must not be empty");
+        for (const e of list) {
+            if (!e.name)
+                throw new Error("client.send: event.name is required");
+        }
+        const resp = await fetch(`${baseUrl}/v1/events`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${opts.eventKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(Array.isArray(events) ? list : list[0]),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            throw new Error(`client.send: platform returned ${resp.status}: ${text}`);
+        }
+        return (await resp.json());
+    }
+    function register(serveUrl, regOpts = {}) {
+        if (!opts.eventKey)
+            throw new Error("client.register: eventKey is required (createClient 时传入)");
+        if (!serveUrl)
+            throw new Error("client.register: serveUrl is required");
+        const intervalMs = regOpts.intervalMs ?? 2000;
+        const maxAttempts = regOpts.attempts ?? 150;
+        let attempts = 0;
+        const tryRegister = async () => {
+            attempts++;
+            try {
+                const resp = await fetch(`${baseUrl}/api/v1/apps`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${opts.eventKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ url: serveUrl }),
+                });
+                if (resp.ok) {
+                    console.log(`[triggerlink] registered ${serveUrl} (platform ${resp.status})`);
+                    return;
+                }
+                console.warn(`[triggerlink] register #${attempts}: platform HTTP ${resp.status}`);
+            }
+            catch (err) {
+                console.warn(`[triggerlink] register #${attempts}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (attempts < maxAttempts)
+                setTimeout(tryRegister, intervalMs);
+            else
+                console.warn("[triggerlink] register gave up, please POST /api/v1/apps manually");
+        };
+        void tryRegister();
+    }
+    return { id: opts.id, signingKey: opts.signingKey, send, register };
+}

package/dist/execx.d.ts

@@ -0,0 +1,45 @@
+/** 平台注入的单个 step memo。 */
+export interface StepState {
+    id: string;
+    status: string;
+    output?: unknown;
+}
+export interface OpError {
+    message: string;
+    stack?: string;
+    retryable: boolean;
+}
+/** 应用 → 平台的执行指令（serve 序列化为响应）。 */
+export interface Opcode {
+    op: "StepComplete" | "StepError" | "RunComplete" | "RunError" | "Sleep" | "SendEvent";
+    id?: string;
+    step_id?: string;
+    output?: unknown;
+    error?: OpError;
+    until?: string;
+    events?: OutgoingEvent[];
+}
+/** step.sendEvent 待扇出的事件（id/ts 缺省由平台补全，id 缺省为确定性派生）。 */
+export interface OutgoingEvent {
+    id?: string;
+    name: string;
+    data?: unknown;
+    ts?: string;
+}
+/** step 中断：正常控制流，由 serve 捕获并序列化为 opcode。 */
+export declare class StepInterrupt extends Error {
+    readonly opcode: Opcode;
+    constructor(opcode: Opcode);
+}
+/** 单次函数调用的执行上下文。 */
+export declare class ExecCtx {
+    readonly functionId: string;
+    readonly steps: Record<string, StepState>;
+    private readonly counters;
+    constructor(functionId: string, steps?: Record<string, StepState>);
+    /**
+     * memo 键：hex(sha256(functionID + ":" + stepID + ":" + 序号))，序号从 0 起。
+     * 平台视其为不透明字符串，只要求同一 run 多次重入间确定（协议第 6 节）。
+     */
+    nextHash(stepId: string): string;
+}

package/dist/execx.js

@@ -0,0 +1,30 @@
+// 执行上下文与 opcode 类型（协议第 4/5/6 节；对应 Go 的 sdk/internal/execx）。
+import { createHash } from "node:crypto";
+/** step 中断：正常控制流，由 serve 捕获并序列化为 opcode。 */
+export class StepInterrupt extends Error {
+    opcode;
+    constructor(opcode) {
+        super(`step interrupt: ${opcode.op}`);
+        this.name = "StepInterrupt";
+        this.opcode = opcode;
+    }
+}
+/** 单次函数调用的执行上下文。 */
+export class ExecCtx {
+    functionId;
+    steps;
+    counters = new Map();
+    constructor(functionId, steps) {
+        this.functionId = functionId;
+        this.steps = steps ?? {};
+    }
+    /**
+     * memo 键：hex(sha256(functionID + ":" + stepID + ":" + 序号))，序号从 0 起。
+     * 平台视其为不透明字符串，只要求同一 run 多次重入间确定（协议第 6 节）。
+     */
+    nextHash(stepId) {
+        const n = this.counters.get(stepId) ?? 0;
+        this.counters.set(stepId, n + 1);
+        return createHash("sha256").update(`${this.functionId}:${stepId}:${n}`).digest("hex");
+    }
+}

package/dist/function.d.ts

@@ -0,0 +1,29 @@
+import type { StepTool } from "./step.js";
+/** 触发函数的事件（与平台 eventPayload 同构）。 */
+export interface EventPayload<T = unknown> {
+    id: string;
+    name: string;
+    data: T;
+    ts: string;
+}
+/** 传给用户 handler 的上下文。 */
+export interface HandlerContext<T = unknown> {
+    event: EventPayload<T>;
+    step: StepTool;
+    runId: string;
+    attempt: number;
+}
+export interface FunctionOpts {
+    /** 稳定标识，改名会丢历史 memo 关联 */
+    id: string;
+    /** 订阅的事件名 */
+    event: string;
+    /** 重试上限；0/缺省 = 平台默认（4） */
+    retries?: number;
+}
+export interface TriggerFunction<T = unknown> {
+    readonly opts: Required<FunctionOpts>;
+    readonly handler: (ctx: HandlerContext<T>) => Promise<unknown>;
+}
+/** 定义一个 durable 函数。副作用必须放进 step.run（协议第 6 节约束）。 */
+export declare function createFunction<T = unknown>(opts: FunctionOpts, handler: (ctx: HandlerContext<T>) => Promise<unknown>): TriggerFunction<T>;

package/dist/function.js

@@ -0,0 +1,8 @@
+/** 定义一个 durable 函数。副作用必须放进 step.run（协议第 6 节约束）。 */
+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");
+    return { opts: { retries: 0, ...opts }, handler };
+}

package/dist/index.d.ts

@@ -0,0 +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 { serve, sdkVersion, type ServeOptions } from "./serve.js";
+export { StepInterrupt, type Opcode, type StepState, type OutgoingEvent } from "./execx.js";
+export type { StepTool } from "./step.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @triggerlink/sdk — TriggerLink TypeScript SDK（M0 原型）。
+// 用法见 sdk-ts/README.md 与 docs/protocol.md。
+export { createClient, } from "./client.js";
+export { createFunction, } from "./function.js";
+export { serve, sdkVersion } from "./serve.js";
+export { StepInterrupt } from "./execx.js";

package/dist/serve.d.ts

@@ -0,0 +1,12 @@
+import type { Client } from "./client.js";
+import type { TriggerFunction } from "./function.js";
+export declare const sdkVersion = "triggerlink-ts/0.3.0";
+export declare const SIGNATURE_HEADER = "x-triggerlink-signature";
+export interface ServeOptions {
+    client: Client;
+    functions: TriggerFunction[];
+}
+export declare function serve(opts: ServeOptions): {
+    GET: (req: Request) => Promise<Response>;
+    POST: (req: Request) => Promise<Response>;
+};

package/dist/serve.js

@@ -0,0 +1,68 @@
+import { ExecCtx, StepInterrupt } from "./execx.js";
+import { createStepTool, errMessage } from "./step.js";
+import { verifySignature } from "./sign.js";
+export const sdkVersion = "triggerlink-ts/0.3.0";
+export const SIGNATURE_HEADER = "x-triggerlink-signature";
+const MAX_BODY = 10 << 20; // 10 MB，与平台一致
+function json(data, status = 200) {
+    return Response.json(data, { status });
+}
+export function serve(opts) {
+    const byID = new Map();
+    for (const fn of opts.functions)
+        byID.set(fn.opts.id, fn);
+    async function GET(req) {
+        if (!verifySignature(opts.client.signingKey, req.headers.get(SIGNATURE_HEADER), new Uint8Array(0))) {
+            return json({ error: "unauthorized" }, 401);
+        }
+        return json({
+            sdk: sdkVersion,
+            app_id: opts.client.id,
+            functions: [...byID.values()].map((f) => ({
+                id: f.opts.id,
+                event: f.opts.event,
+                retries: f.opts.retries,
+            })),
+        });
+    }
+    async function POST(req) {
+        const body = new Uint8Array(await req.arrayBuffer());
+        if (body.byteLength > MAX_BODY)
+            return json({ error: "body too large" }, 400);
+        if (!verifySignature(opts.client.signingKey, req.headers.get(SIGNATURE_HEADER), body)) {
+            return json({ error: "unauthorized" }, 401);
+        }
+        let cbReq;
+        try {
+            cbReq = JSON.parse(new TextDecoder().decode(body));
+        }
+        catch {
+            return json({ error: "invalid request" }, 400);
+        }
+        const fn = byID.get(cbReq?.ctx?.function_id);
+        if (!fn)
+            return json({ error: "function not found" }, 404);
+        const ec = new ExecCtx(cbReq.ctx.function_id, cbReq.ctx.steps);
+        const step = createStepTool(ec);
+        let opcode;
+        try {
+            const output = await fn.handler({
+                event: cbReq.ctx.event,
+                step,
+                runId: cbReq.ctx.run_id,
+                attempt: cbReq.ctx.attempt,
+            });
+            opcode = { op: "RunComplete", output };
+        }
+        catch (err) {
+            if (err instanceof StepInterrupt) {
+                opcode = err.opcode;
+            }
+            else {
+                opcode = { op: "RunError", error: { message: errMessage(err), retryable: true } };
+            }
+        }
+        return json(opcode);
+    }
+    return { GET, POST };
+}

package/dist/sign.d.ts

@@ -0,0 +1,4 @@
+/** 生成签名头部值（平台侧模拟、测试用；SDK 正常路径只验签）。 */
+export declare function sign(key: string, body: Uint8Array, now?: Date): string;
+/** 校验签名头部值；不合法一律返回 false（调用方应回 401）。 */
+export declare function verifySignature(key: string, header: string | null, body: Uint8Array): boolean;

package/dist/sign.js

@@ -0,0 +1,40 @@
+// 平台↔应用 HMAC-SHA256 签名验证（协议第 2 节）。
+// 头部格式：t=<unix秒>,v1=<hex(hmac_sha256(key, "<t>.<body>"))>
+import { createHmac, timingSafeEqual } from "node:crypto";
+const TOLERANCE_SEC = 5 * 60; // ±5 分钟，与 Go SDK 一致
+function computeSig(key, ts, body) {
+    const mac = createHmac("sha256", key);
+    mac.update(`${ts}.`);
+    mac.update(body);
+    return mac.digest("hex");
+}
+/** 生成签名头部值（平台侧模拟、测试用；SDK 正常路径只验签）。 */
+export function sign(key, body, now = new Date()) {
+    const t = Math.floor(now.getTime() / 1000).toString();
+    return `t=${t},v1=${computeSig(key, t, body)}`;
+}
+/** 校验签名头部值；不合法一律返回 false（调用方应回 401）。 */
+export function verifySignature(key, header, body) {
+    if (!header)
+        return false;
+    let ts = "";
+    let sig = "";
+    for (const part of header.split(",")) {
+        if (part.startsWith("t="))
+            ts = part.slice(2);
+        else if (part.startsWith("v1="))
+            sig = part.slice(3);
+    }
+    if (!ts || !sig)
+        return false;
+    const sec = Number(ts);
+    if (!Number.isFinite(sec))
+        return false;
+    const skew = Math.abs(Date.now() / 1000 - sec);
+    if (skew > TOLERANCE_SEC)
+        return false;
+    const expected = computeSig(key, ts, body);
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(sig, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/step.d.ts

@@ -0,0 +1,25 @@
+import { ExecCtx, type OutgoingEvent } from "./execx.js";
+/** handler 内可用的 step 工具。 */
+export interface StepTool {
+    /**
+     * 执行一个 durable step：fn 的返回值被平台持久化，崩溃恢复后直接注入不重跑。
+     * memo 命中 → 返回缓存值；未命中 → 执行 fn，然后抛 StepInterrupt 中断函数，
+     * 由 serve 序列化为 opcode 交平台持久化并发起下一次回调。
+     */
+    run<T>(id: string, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * 挂起当前 run 直至 durMs 之后：函数中断，平台到点重新回调恢复。
+     * 挂起期间不占连接与计算；恢复重入时 memo 命中直接返回，不会重复睡眠。
+     */
+    sleep(id: string, durMs: number): Promise<void>;
+    /** 挂起当前 run 直至绝对时刻 at（sleep 的绝对时间版本）。 */
+    sleepUntil(id: string, at: Date | string): Promise<void>;
+    /**
+     * 在函数内可靠扇出事件：平台先落库后路由，崩溃不丢。
+     * memo 语义同 run——恢复重入时直接返回已发事件 ID 列表，不会重复发送。
+     */
+    sendEvent(id: string, events: OutgoingEvent | OutgoingEvent[]): Promise<string[]>;
+}
+/** 为一次函数调用构造 step 工具。 */
+export declare function createStepTool(ec: ExecCtx): StepTool;
+export declare function errMessage(err: unknown): string;

package/dist/step.js

@@ -0,0 +1,55 @@
+// step 原语（协议第 5/6 节；对应 Go 的 sdk/step）。
+import { StepInterrupt } from "./execx.js";
+/** 为一次函数调用构造 step 工具。 */
+export function createStepTool(ec) {
+    return {
+        async run(id, fn) {
+            const h = ec.nextHash(id);
+            const memo = ec.steps[h];
+            if (memo && memo.status === "completed") {
+                return memo.output;
+            }
+            try {
+                const output = await fn();
+                throw new StepInterrupt({ op: "StepComplete", id: h, step_id: id, output });
+            }
+            catch (err) {
+                if (err instanceof StepInterrupt)
+                    throw err;
+                throw new StepInterrupt({
+                    op: "StepError",
+                    id: h,
+                    step_id: id,
+                    error: { message: errMessage(err), stack: errStack(err), retryable: true },
+                });
+            }
+        },
+        async sleep(id, durMs) {
+            return this.sleepUntil(id, new Date(Date.now() + durMs));
+        },
+        async sleepUntil(id, at) {
+            const h = ec.nextHash(id);
+            const memo = ec.steps[h];
+            if (memo && memo.status === "completed")
+                return; // 已睡过（平台唤醒时已置 completed）
+            const until = (typeof at === "string" ? new Date(at) : at).toISOString();
+            throw new StepInterrupt({ op: "Sleep", id: h, step_id: id, until });
+        },
+        async sendEvent(id, events) {
+            const h = ec.nextHash(id);
+            const memo = ec.steps[h];
+            if (memo && memo.status === "completed")
+                return memo.output;
+            const list = Array.isArray(events) ? events : [events];
+            if (list.length === 0)
+                throw new Error(`step.sendEvent "${id}": no events`);
+            throw new StepInterrupt({ op: "SendEvent", id: h, step_id: id, events: list });
+        },
+    };
+}
+export function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function errStack(err) {
+    return err instanceof Error ? err.stack : undefined;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@triggerlink/sdk",
+  "version": "0.3.0",
+  "description": "TriggerLink TypeScript SDK (M0 prototype): durable functions for Next.js / Node.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.mjs\""
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Richardo1o1/TriggerLink.git",
+    "directory": "sdk-ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}