@headless-lms/adapter-workflow-hatchet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdwt
+
+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,35 @@
+# @headless-lms/adapter-workflow-hatchet
+
+Hatchet ([hatchet.run](https://hatchet.run)) implementation of the `AutomationEngine`
+port from `@headless-lms/core/types` — durable execution for dispatched automations.
+
+The adapter declares one workflow, `automation-run`: a durable parent task that
+iterates the dispatched actions, spawning one child task per action
+(`automation-run-action`, `retries: 3`) through Hatchet's durable event log. A
+child that exhausts its retries stops the sequence; the parent then calls
+`finalize` exactly once with the results collected so far. Because children are
+spawned via the durable event log, a crash mid-run resumes after the last
+completed action instead of restarting the sequence from scratch.
+
+```ts
+import { HatchetAutomationEngine } from "@headless-lms/adapter-workflow-hatchet";
+
+const container = await createContainer(config, {
+  adapters: { automationEngine: new HatchetAutomationEngine() },
+});
+```
+
+The Hatchet client reads its own environment (`HATCHET_CLIENT_TOKEN` and friends —
+see the [Hatchet docs](https://docs.hatchet.run/home/setup)); this adapter reads
+none of it itself. Pass a pre-built client (or a fake, satisfying
+`HatchetClientLike`) as the first constructor argument for tests or non-default
+setups.
+
+## Environment variables (Hatchet client, read by the SDK)
+
+| Variable              | Required | Notes                                   |
+| --------------------- | -------- | ---------------------------------------- |
+| `HATCHET_CLIENT_TOKEN` | yes     | Hatchet API token for the target tenant. |
+
+See the Hatchet TypeScript SDK docs for the full set of `HATCHET_CLIENT_*` variables
+(host/port, TLS, namespace, …).

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { AutomationActionResult, AutomationDispatch, AutomationEngine, AutomationExecutor, Logger } from "@headless-lms/core/types";
+//#region src/index.d.ts
+interface ActionTaskInput {
+  dispatch: AutomationDispatch;
+  index: number;
+}
+/** Subset of `DurableContext` the parent task uses; hand-rolled so tests can fake it without a real Hatchet client. */
+interface DurableCtxLike {
+  spawnChild(task: unknown, input: ActionTaskInput, options?: Record<string, unknown>): Promise<AutomationActionResult>;
+}
+interface RunnableTask<I> {
+  runNoWait(input: I): Promise<unknown>;
+}
+interface HatchetWorkerLike {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+/** Subset of the Hatchet v1 client this adapter calls; hand-rolled so tests can inject a fake client. */
+interface HatchetClientLike {
+  task(opts: {
+    name: string;
+    retries?: number;
+    fn: (input: ActionTaskInput, ctx: unknown) => Promise<AutomationActionResult> | AutomationActionResult;
+  }): unknown;
+  durableTask(opts: {
+    name: string;
+    fn: (input: AutomationDispatch, ctx: DurableCtxLike) => Promise<void>;
+  }): RunnableTask<AutomationDispatch>;
+  worker(name: string, opts: {
+    workflows: any[];
+  }): Promise<HatchetWorkerLike>;
+}
+declare class HatchetAutomationEngine implements AutomationEngine {
+  private readonly client;
+  private readonly logger?;
+  private executor;
+  private worker;
+  private readonly actionTask;
+  private readonly automationRunTask;
+  /** `client` defaults to a Hatchet client built from env (`HATCHET_CLIENT_TOKEN`); pass a fake for tests. */
+  constructor(client?: HatchetClientLike, logger?: Logger | undefined);
+  register(executor: AutomationExecutor): void;
+  dispatch(d: AutomationDispatch): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** Lets failures throw so Hatchet's per-task retry (retries: 3) applies before the parent gives up. */
+  private runAction;
+  private runDispatch;
+}
+//#endregion
+export { HatchetAutomationEngine, HatchetClientLike };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,75 @@
+import { Hatchet } from "@hatchet-dev/typescript-sdk";
+//#region src/index.ts
+const WORKFLOW_NAME = "automation-run";
+const ACTION_TASK_NAME = "automation-run-action";
+const WORKER_NAME = "automation-run-worker";
+var HatchetAutomationEngine = class {
+	client;
+	logger;
+	executor;
+	worker;
+	actionTask;
+	automationRunTask;
+	/** `client` defaults to a Hatchet client built from env (`HATCHET_CLIENT_TOKEN`); pass a fake for tests. */
+	constructor(client = new Hatchet(), logger) {
+		this.client = client;
+		this.logger = logger;
+		this.actionTask = this.client.task({
+			name: ACTION_TASK_NAME,
+			retries: 3,
+			fn: async (input) => this.runAction(input)
+		});
+		this.automationRunTask = this.client.durableTask({
+			name: WORKFLOW_NAME,
+			fn: async (dispatch, ctx) => this.runDispatch(dispatch, ctx)
+		});
+	}
+	register(executor) {
+		this.executor = executor;
+	}
+	async dispatch(d) {
+		if (!this.executor) throw new Error("HatchetAutomationEngine.dispatch called before register()");
+		await this.automationRunTask.runNoWait(d);
+	}
+	async start() {
+		if (!this.executor) throw new Error("HatchetAutomationEngine.start called before register()");
+		this.worker = await this.client.worker(WORKER_NAME, { workflows: [this.actionTask, this.automationRunTask] });
+		this.worker.start().catch((err) => {
+			this.logger?.error("hatchet worker stopped unexpectedly", { error: String(err) });
+		});
+	}
+	async stop() {
+		await this.worker?.stop();
+		this.worker = void 0;
+	}
+	/** Lets failures throw so Hatchet's per-task retry (retries: 3) applies before the parent gives up. */
+	async runAction(input) {
+		if (!this.executor) throw new Error("HatchetAutomationEngine: automation-run-action invoked before register()");
+		return this.executor.runAction(input.dispatch, input.index);
+	}
+	async runDispatch(dispatch, ctx) {
+		if (!this.executor) throw new Error("HatchetAutomationEngine: automation-run invoked before register()");
+		const executor = this.executor;
+		const results = [];
+		for (let index = 0; index < dispatch.actions.length; index++) try {
+			results.push(await ctx.spawnChild(this.actionTask, {
+				dispatch,
+				index
+			}));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			results.push({
+				index,
+				type: dispatch.actions[index].type,
+				status: "failed",
+				error: message
+			});
+			break;
+		}
+		await executor.finalize(dispatch, results);
+	}
+};
+//#endregion
+export { HatchetAutomationEngine };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// Hatchet implementation of the AutomationEngine port — durable execution via\n// hatchet.run. The \"automation-run\" durable parent task spawns one child task\n// (\"automation-run-action\", retries: 3) per action through the durable event\n// log, stopping on the first exhausted child; the parent then finalizes once\n// with the results collected so far.\nimport type { Logger, AutomationDispatch, AutomationExecutor, AutomationEngine, AutomationActionResult } from \"@headless-lms/core/types\";\nimport { Hatchet } from \"@hatchet-dev/typescript-sdk\";\n\nconst WORKFLOW_NAME = \"automation-run\";\nconst ACTION_TASK_NAME = \"automation-run-action\";\nconst WORKER_NAME = \"automation-run-worker\";\n\ninterface ActionTaskInput {\n  dispatch: AutomationDispatch;\n  index: number;\n}\n\n/** Subset of `DurableContext` the parent task uses; hand-rolled so tests can fake it without a real Hatchet client. */\ninterface DurableCtxLike {\n  spawnChild(task: unknown, input: ActionTaskInput, options?: Record<string, unknown>): Promise<AutomationActionResult>;\n}\n\ninterface RunnableTask<I> {\n  runNoWait(input: I): Promise<unknown>;\n}\n\ninterface HatchetWorkerLike {\n  start(): Promise<void>;\n  stop(): Promise<void>;\n}\n\n/** Subset of the Hatchet v1 client this adapter calls; hand-rolled so tests can inject a fake client. */\nexport interface HatchetClientLike {\n  task(opts: {\n    name: string;\n    retries?: number;\n    fn: (input: ActionTaskInput, ctx: unknown) => Promise<AutomationActionResult> | AutomationActionResult;\n  }): unknown;\n  durableTask(opts: {\n    name: string;\n    fn: (input: AutomationDispatch, ctx: DurableCtxLike) => Promise<void>;\n  }): RunnableTask<AutomationDispatch>;\n  worker(name: string, opts: { workflows: any[] }): Promise<HatchetWorkerLike>; // eslint-disable-line @typescript-eslint/no-explicit-any -- bridges to the SDK's own workflow union type without importing it\n}\n\nexport class HatchetAutomationEngine implements AutomationEngine {\n  private executor: AutomationExecutor | undefined;\n  private worker: HatchetWorkerLike | undefined;\n  private readonly actionTask: unknown;\n  private readonly automationRunTask: RunnableTask<AutomationDispatch>;\n\n  /** `client` defaults to a Hatchet client built from env (`HATCHET_CLIENT_TOKEN`); pass a fake for tests. */\n  constructor(\n    private readonly client: HatchetClientLike = new Hatchet(),\n    private readonly logger?: Logger,\n  ) {\n    this.actionTask = this.client.task({\n      name: ACTION_TASK_NAME,\n      retries: 3,\n      fn: async (input) => this.runAction(input),\n    });\n\n    this.automationRunTask = this.client.durableTask({\n      name: WORKFLOW_NAME,\n      fn: async (dispatch, ctx) => this.runDispatch(dispatch, ctx),\n    });\n  }\n\n  register(executor: AutomationExecutor): void {\n    this.executor = executor;\n  }\n\n  async dispatch(d: AutomationDispatch): Promise<void> {\n    if (!this.executor) {\n      throw new Error(\"HatchetAutomationEngine.dispatch called before register()\");\n    }\n    await this.automationRunTask.runNoWait(d);\n  }\n\n  async start(): Promise<void> {\n    if (!this.executor) {\n      throw new Error(\"HatchetAutomationEngine.start called before register()\");\n    }\n    this.worker = await this.client.worker(WORKER_NAME, {\n      workflows: [this.actionTask, this.automationRunTask],\n    });\n    // worker.start() resolves only once the worker stops — run it in the background.\n    void this.worker.start().catch((err: unknown) => {\n      this.logger?.error(\"hatchet worker stopped unexpectedly\", { error: String(err) });\n    });\n  }\n\n  async stop(): Promise<void> {\n    await this.worker?.stop();\n    this.worker = undefined;\n  }\n\n  /** Lets failures throw so Hatchet's per-task retry (retries: 3) applies before the parent gives up. */\n  private async runAction(input: ActionTaskInput): Promise<AutomationActionResult> {\n    if (!this.executor) {\n      throw new Error(\"HatchetAutomationEngine: automation-run-action invoked before register()\");\n    }\n    return this.executor.runAction(input.dispatch, input.index);\n  }\n\n  private async runDispatch(dispatch: AutomationDispatch, ctx: DurableCtxLike): Promise<void> {\n    if (!this.executor) {\n      throw new Error(\"HatchetAutomationEngine: automation-run invoked before register()\");\n    }\n    const executor = this.executor;\n\n    const results: AutomationActionResult[] = [];\n    for (let index = 0; index < dispatch.actions.length; index++) {\n      try {\n        results.push(await ctx.spawnChild(this.actionTask, { dispatch, index }));\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        results.push({ index, type: dispatch.actions[index]!.type, status: \"failed\", error: message });\n        break;\n      }\n    }\n\n    // A crash before this task completes replays finalize on resume — finalize and its downstream events must tolerate duplicates.\n    await executor.finalize(dispatch, results);\n  }\n}\n"],"mappings":";;AAQA,MAAM,gBAAgB;AACtB,MAAM,mBAAmB;AACzB,MAAM,cAAc;AAmCpB,IAAa,0BAAb,MAAiE;CAQ5C;CACA;CARnB;CACA;CACA;CACA;;CAGA,YACE,SAA6C,IAAI,QAAQ,GACzD,QACA;EAFiB,KAAA,SAAA;EACA,KAAA,SAAA;EAEjB,KAAK,aAAa,KAAK,OAAO,KAAK;GACjC,MAAM;GACN,SAAS;GACT,IAAI,OAAO,UAAU,KAAK,UAAU,KAAK;EAC3C,CAAC;EAED,KAAK,oBAAoB,KAAK,OAAO,YAAY;GAC/C,MAAM;GACN,IAAI,OAAO,UAAU,QAAQ,KAAK,YAAY,UAAU,GAAG;EAC7D,CAAC;CACH;CAEA,SAAS,UAAoC;EAC3C,KAAK,WAAW;CAClB;CAEA,MAAM,SAAS,GAAsC;EACnD,IAAI,CAAC,KAAK,UACR,MAAM,IAAI,MAAM,2DAA2D;EAE7E,MAAM,KAAK,kBAAkB,UAAU,CAAC;CAC1C;CAEA,MAAM,QAAuB;EAC3B,IAAI,CAAC,KAAK,UACR,MAAM,IAAI,MAAM,wDAAwD;EAE1E,KAAK,SAAS,MAAM,KAAK,OAAO,OAAO,aAAa,EAClD,WAAW,CAAC,KAAK,YAAY,KAAK,iBAAiB,EACrD,CAAC;EAED,KAAU,OAAO,MAAM,CAAC,CAAC,OAAO,QAAiB;GAC/C,KAAK,QAAQ,MAAM,uCAAuC,EAAE,OAAO,OAAO,GAAG,EAAE,CAAC;EAClF,CAAC;CACH;CAEA,MAAM,OAAsB;EAC1B,MAAM,KAAK,QAAQ,KAAK;EACxB,KAAK,SAAS,KAAA;CAChB;;CAGA,MAAc,UAAU,OAAyD;EAC/E,IAAI,CAAC,KAAK,UACR,MAAM,IAAI,MAAM,0EAA0E;EAE5F,OAAO,KAAK,SAAS,UAAU,MAAM,UAAU,MAAM,KAAK;CAC5D;CAEA,MAAc,YAAY,UAA8B,KAAoC;EAC1F,IAAI,CAAC,KAAK,UACR,MAAM,IAAI,MAAM,mEAAmE;EAErF,MAAM,WAAW,KAAK;EAEtB,MAAM,UAAoC,CAAC;EAC3C,KAAK,IAAI,QAAQ,GAAG,QAAQ,SAAS,QAAQ,QAAQ,SACnD,IAAI;GACF,QAAQ,KAAK,MAAM,IAAI,WAAW,KAAK,YAAY;IAAE;IAAU;GAAM,CAAC,CAAC;EACzE,SAAS,KAAK;GACZ,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;GAC/D,QAAQ,KAAK;IAAE;IAAO,MAAM,SAAS,QAAQ,MAAM,CAAE;IAAM,QAAQ;IAAU,OAAO;GAAQ,CAAC;GAC7F;EACF;EAIF,MAAM,SAAS,SAAS,UAAU,OAAO;CAC3C;AACF"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@headless-lms/adapter-workflow-hatchet",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@hatchet-dev/typescript-sdk": "^1.28.0",
+    "@headless-lms/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "description": "Hatchet workflow adapter for the headless LMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "adapters/workflow-hatchet"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}