@temporal-contract/client 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+import { ClientOptions, WorkflowHandle, WorkflowOptions, WorkflowStartOptions } from "@temporalio/client";
+import { z } from "zod";
+import { ClientInferInput, ClientInferOutput, ClientInferWorkflowQueries, ClientInferWorkflowSignals, ClientInferWorkflowUpdates, ContractDefinition, WorkflowDefinition } from "@temporal-contract/contract";
+
+//#region src/client.d.ts
+
+/**
+ * Extended options for starting workflows with Temporal-specific features
+ * Combines required workflowId with optional Temporal workflow options
+ */
+type TypedWorkflowStartOptions = Pick<WorkflowStartOptions, "workflowId" | "workflowIdReusePolicy" | "workflowExecutionTimeout" | "workflowRunTimeout" | "workflowTaskTimeout" | "retry" | "memo" | "searchAttributes" | "cronSchedule"> & Pick<WorkflowOptions, "workflowId">;
+/**
+ * Typed workflow handle with validated results, queries, signals and updates
+ */
+interface TypedWorkflowHandle<TWorkflow extends WorkflowDefinition> {
+  workflowId: string;
+  /**
+   * Type-safe queries based on workflow definition
+   */
+  queries: ClientInferWorkflowQueries<TWorkflow>;
+  /**
+   * Type-safe signals based on workflow definition
+   */
+  signals: ClientInferWorkflowSignals<TWorkflow>;
+  /**
+   * Type-safe updates based on workflow definition
+   */
+  updates: ClientInferWorkflowUpdates<TWorkflow>;
+  result: () => Promise<ClientInferOutput<TWorkflow>>;
+  terminate: (reason?: string) => Promise<void>;
+  cancel: () => Promise<void>;
+  /**
+   * Get workflow execution description including status and metadata
+   *
+   * @example
+   * ```ts
+   * const handle = await client.getHandle('processOrder', 'order-123');
+   * const description = await handle.describe();
+   * console.log(description.workflowExecutionInfo.status); // RUNNING, COMPLETED, etc.
+   * ```
+   */
+  describe: () => ReturnType<WorkflowHandle["describe"]>;
+  /**
+   * Fetch the workflow execution history
+   *
+   * @example
+   * ```ts
+   * const handle = await client.getHandle('processOrder', 'order-123');
+   * const history = handle.fetchHistory();
+   * for await (const event of history) {
+   *   console.log(event);
+   * }
+   * ```
+   */
+  fetchHistory: () => ReturnType<WorkflowHandle["fetchHistory"]>;
+}
+/**
+ * Typed Temporal client based on a contract
+ *
+ * Provides type-safe methods to start and execute workflows
+ * defined in the contract.
+ */
+declare class TypedClient<TContract extends ContractDefinition> {
+  private readonly contract;
+  private readonly client;
+  private constructor();
+  /**
+   * Create a typed Temporal client from a contract
+   *
+   * @example
+   * ```ts
+   * const connection = await Connection.connect();
+   * const client = TypedClient.create(myContract, {
+   *   connection,
+   *   namespace: 'default',
+   * });
+   *
+   * const result = await client.executeWorkflow('processOrder', {
+   *   workflowId: 'order-123',
+   *   args: [...],
+   * });
+   * ```
+   */
+  static create<TContract extends ContractDefinition>(contract: TContract, options: ClientOptions): TypedClient<TContract>;
+  /**
+   * Start a workflow and return a typed handle
+   *
+   * @example
+   * ```ts
+   * const handle = await client.startWorkflow('processOrder', {
+   *   workflowId: 'order-123',
+   *   args: ['ORD-123', 'CUST-456', [{ productId: 'PROD-1', quantity: 2 }]],
+   *   workflowExecutionTimeout: '1 day',
+   *   retry: { maximumAttempts: 3 },
+   * });
+   *
+   * const result = await handle.result();
+   * ```
+   */
+  startWorkflow<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, {
+    args,
+    ...temporalOptions
+  }: TypedWorkflowStartOptions & {
+    args: ClientInferInput<TContract["workflows"][TWorkflowName]>;
+  }): Promise<TypedWorkflowHandle<TContract["workflows"][TWorkflowName]>>;
+  /**
+   * Execute a workflow (start and wait for result)
+   *
+   * @example
+   * ```ts
+   * const result = await client.executeWorkflow('processOrder', {
+   *   workflowId: 'order-123',
+   *   args: ['ORD-123', 'CUST-456', [{ productId: 'PROD-1', quantity: 2 }]],
+   *   workflowExecutionTimeout: '1 day',
+   *   retry: { maximumAttempts: 3 },
+   * });
+   *
+   * console.log(result.status); // fully typed!
+   * ```
+   */
+  executeWorkflow<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, {
+    args,
+    ...temporalOptions
+  }: TypedWorkflowStartOptions & {
+    args: ClientInferInput<TContract["workflows"][TWorkflowName]>;
+  }): Promise<ClientInferOutput<TContract["workflows"][TWorkflowName]>>;
+  /**
+   * Get a handle to an existing workflow
+   *
+   * @example
+   * ```ts
+   * const handle = await client.getHandle('processOrder', 'order-123');
+   * const result = await handle.result();
+   * ```
+   */
+  getHandle<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, workflowId: string): Promise<TypedWorkflowHandle<TContract["workflows"][TWorkflowName]>>;
+  private createTypedHandle;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Base error class for typed client errors
+ */
+declare class TypedClientError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a workflow is not found in the contract
+ */
+declare class WorkflowNotFoundError extends TypedClientError {
+  readonly workflowName: string;
+  constructor(workflowName: string);
+}
+/**
+ * Error thrown when workflow input or output validation fails
+ */
+declare class WorkflowValidationError extends TypedClientError {
+  readonly workflowName: string;
+  readonly phase: "input" | "output";
+  readonly zodError: z.ZodError;
+  constructor(workflowName: string, phase: "input" | "output", zodError: z.ZodError);
+}
+/**
+ * Error thrown when query input or output validation fails
+ */
+declare class QueryValidationError extends TypedClientError {
+  readonly queryName: string;
+  readonly phase: "input" | "output";
+  readonly zodError: z.ZodError;
+  constructor(queryName: string, phase: "input" | "output", zodError: z.ZodError);
+}
+/**
+ * Error thrown when signal input validation fails
+ */
+declare class SignalValidationError extends TypedClientError {
+  readonly signalName: string;
+  readonly zodError: z.ZodError;
+  constructor(signalName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when update input or output validation fails
+ */
+declare class UpdateValidationError extends TypedClientError {
+  readonly updateName: string;
+  readonly phase: "input" | "output";
+  readonly zodError: z.ZodError;
+  constructor(updateName: string, phase: "input" | "output", zodError: z.ZodError);
+}
+//#endregion
+export { QueryValidationError, SignalValidationError, TypedClient, TypedClientError, type TypedWorkflowHandle, type TypedWorkflowStartOptions, UpdateValidationError, WorkflowNotFoundError, WorkflowValidationError };

package/dist/index.mjs

@@ -0,0 +1,263 @@
+import { Client } from "@temporalio/client";
+import { ZodError } from "zod";
+
+//#region src/errors.ts
+/**
+* Base error class for typed client errors
+*/
+var TypedClientError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TypedClientError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+/**
+* Error thrown when a workflow is not found in the contract
+*/
+var WorkflowNotFoundError = class extends TypedClientError {
+	constructor(workflowName) {
+		super(`Workflow "${workflowName}" not found in contract`);
+		this.workflowName = workflowName;
+		this.name = "WorkflowNotFoundError";
+	}
+};
+/**
+* Error thrown when workflow input or output validation fails
+*/
+var WorkflowValidationError = class extends TypedClientError {
+	constructor(workflowName, phase, zodError) {
+		super(`Validation failed for workflow "${workflowName}" ${phase}: ${zodError.message}`);
+		this.workflowName = workflowName;
+		this.phase = phase;
+		this.zodError = zodError;
+		this.name = "WorkflowValidationError";
+	}
+};
+/**
+* Error thrown when query input or output validation fails
+*/
+var QueryValidationError = class extends TypedClientError {
+	constructor(queryName, phase, zodError) {
+		super(`Validation failed for query "${queryName}" ${phase}: ${zodError.message}`);
+		this.queryName = queryName;
+		this.phase = phase;
+		this.zodError = zodError;
+		this.name = "QueryValidationError";
+	}
+};
+/**
+* Error thrown when signal input validation fails
+*/
+var SignalValidationError = class extends TypedClientError {
+	constructor(signalName, zodError) {
+		super(`Validation failed for signal "${signalName}" input: ${zodError.message}`);
+		this.signalName = signalName;
+		this.zodError = zodError;
+		this.name = "SignalValidationError";
+	}
+};
+/**
+* Error thrown when update input or output validation fails
+*/
+var UpdateValidationError = class extends TypedClientError {
+	constructor(updateName, phase, zodError) {
+		super(`Validation failed for update "${updateName}" ${phase}: ${zodError.message}`);
+		this.updateName = updateName;
+		this.phase = phase;
+		this.zodError = zodError;
+		this.name = "UpdateValidationError";
+	}
+};
+
+//#endregion
+//#region src/client.ts
+/**
+* Typed Temporal client based on a contract
+*
+* Provides type-safe methods to start and execute workflows
+* defined in the contract.
+*/
+var TypedClient = class TypedClient {
+	constructor(contract, client) {
+		this.contract = contract;
+		this.client = client;
+	}
+	/**
+	* Create a typed Temporal client from a contract
+	*
+	* @example
+	* ```ts
+	* const connection = await Connection.connect();
+	* const client = TypedClient.create(myContract, {
+	*   connection,
+	*   namespace: 'default',
+	* });
+	*
+	* const result = await client.executeWorkflow('processOrder', {
+	*   workflowId: 'order-123',
+	*   args: [...],
+	* });
+	* ```
+	*/
+	static create(contract, options) {
+		return new TypedClient(contract, new Client(options));
+	}
+	/**
+	* Start a workflow and return a typed handle
+	*
+	* @example
+	* ```ts
+	* const handle = await client.startWorkflow('processOrder', {
+	*   workflowId: 'order-123',
+	*   args: ['ORD-123', 'CUST-456', [{ productId: 'PROD-1', quantity: 2 }]],
+	*   workflowExecutionTimeout: '1 day',
+	*   retry: { maximumAttempts: 3 },
+	* });
+	*
+	* const result = await handle.result();
+	* ```
+	*/
+	async startWorkflow(workflowName, { args, ...temporalOptions }) {
+		const definition = this.contract.workflows[workflowName];
+		if (!definition) throw new WorkflowNotFoundError(String(workflowName));
+		let validatedInput;
+		try {
+			validatedInput = definition.input.parse(args);
+		} catch (error) {
+			if (error instanceof ZodError) throw new WorkflowValidationError(String(workflowName), "input", error);
+			throw error;
+		}
+		const handle = await this.client.workflow.start(workflowName, {
+			...temporalOptions,
+			taskQueue: this.contract.taskQueue,
+			args: [validatedInput]
+		});
+		return this.createTypedHandle(handle, definition);
+	}
+	/**
+	* Execute a workflow (start and wait for result)
+	*
+	* @example
+	* ```ts
+	* const result = await client.executeWorkflow('processOrder', {
+	*   workflowId: 'order-123',
+	*   args: ['ORD-123', 'CUST-456', [{ productId: 'PROD-1', quantity: 2 }]],
+	*   workflowExecutionTimeout: '1 day',
+	*   retry: { maximumAttempts: 3 },
+	* });
+	*
+	* console.log(result.status); // fully typed!
+	* ```
+	*/
+	async executeWorkflow(workflowName, { args, ...temporalOptions }) {
+		const definition = this.contract.workflows[workflowName];
+		if (!definition) throw new WorkflowNotFoundError(String(workflowName));
+		let validatedInput;
+		try {
+			validatedInput = definition.input.parse(args);
+		} catch (error) {
+			if (error instanceof ZodError) throw new WorkflowValidationError(String(workflowName), "input", error);
+			throw error;
+		}
+		const result = await this.client.workflow.execute(workflowName, {
+			...temporalOptions,
+			taskQueue: this.contract.taskQueue,
+			args: [validatedInput]
+		});
+		try {
+			return definition.output.parse(result);
+		} catch (error) {
+			if (error instanceof ZodError) throw new WorkflowValidationError(String(workflowName), "output", error);
+			throw error;
+		}
+	}
+	/**
+	* Get a handle to an existing workflow
+	*
+	* @example
+	* ```ts
+	* const handle = await client.getHandle('processOrder', 'order-123');
+	* const result = await handle.result();
+	* ```
+	*/
+	async getHandle(workflowName, workflowId) {
+		const definition = this.contract.workflows[workflowName];
+		if (!definition) throw new WorkflowNotFoundError(String(workflowName));
+		const handle = this.client.workflow.getHandle(workflowId);
+		return this.createTypedHandle(handle, definition);
+	}
+	createTypedHandle(handle, definition) {
+		const queries = {};
+		for (const [queryName, queryDef] of Object.entries(definition.queries ?? {})) queries[queryName] = async (args) => {
+			let validatedInput;
+			try {
+				validatedInput = queryDef.input.parse(args);
+			} catch (error) {
+				if (error instanceof ZodError) throw new QueryValidationError(queryName, "input", error);
+				throw error;
+			}
+			const result = await handle.query(queryName, validatedInput);
+			try {
+				return queryDef.output.parse(result);
+			} catch (error) {
+				if (error instanceof ZodError) throw new QueryValidationError(queryName, "output", error);
+				throw error;
+			}
+		};
+		const signals = {};
+		for (const [signalName, signalDef] of Object.entries(definition.signals ?? {})) signals[signalName] = async (args) => {
+			let validatedInput;
+			try {
+				validatedInput = signalDef.input.parse(args);
+			} catch (error) {
+				if (error instanceof ZodError) throw new SignalValidationError(signalName, error);
+				throw error;
+			}
+			await handle.signal(signalName, validatedInput);
+		};
+		const updates = {};
+		for (const [updateName, updateDef] of Object.entries(definition.updates ?? {})) updates[updateName] = async (args) => {
+			let validatedInput;
+			try {
+				validatedInput = updateDef.input.parse(args);
+			} catch (error) {
+				if (error instanceof ZodError) throw new UpdateValidationError(updateName, "input", error);
+				throw error;
+			}
+			const result = await handle.executeUpdate(updateName, { args: [validatedInput] });
+			try {
+				return updateDef.output.parse(result);
+			} catch (error) {
+				if (error instanceof ZodError) throw new UpdateValidationError(updateName, "output", error);
+				throw error;
+			}
+		};
+		return {
+			workflowId: handle.workflowId,
+			queries,
+			signals,
+			updates,
+			result: async () => {
+				const result = await handle.result();
+				try {
+					return definition.output.parse(result);
+				} catch (error) {
+					if (error instanceof ZodError) throw new WorkflowValidationError(handle.workflowId, "output", error);
+					throw error;
+				}
+			},
+			terminate: async (reason) => {
+				await handle.terminate(reason);
+			},
+			cancel: async () => {
+				await handle.cancel();
+			},
+			describe: () => handle.describe(),
+			fetchHistory: () => handle.fetchHistory()
+		};
+	}
+};
+
+//#endregion
+export { QueryValidationError, SignalValidationError, TypedClient, TypedClientError, UpdateValidationError, WorkflowNotFoundError, WorkflowValidationError };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@temporal-contract/client",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Client utilities for consuming temporal-contract workflows",
+  "homepage": "https://github.com/btravers/temporal-contract#readme",
+  "bugs": {
+    "url": "https://github.com/btravers/temporal-contract/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravers/temporal-contract.git",
+    "directory": "packages/client"
+  },
+  "author": "Benoit TRAVERS <benoit.travers.frgmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "temporal",
+    "typescript",
+    "contract",
+    "client"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@temporal-contract/contract": "0.0.1"
+  },
+  "devDependencies": {
+    "@temporalio/client": "1.13.2",
+    "@types/node": "24.10.2",
+    "tsdown": "0.17.2",
+    "type-fest": "5.3.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.15",
+    "zod": "4.1.13",
+    "@temporal-contract/tsconfig": "0.0.1"
+  },
+  "peerDependencies": {
+    "@temporalio/client": ">=1.13.0 <2.0.0",
+    "zod": "^4.0.0"
+  },
+  "scripts": {
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}