@temporal-contract/client 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,17 @@
+
+> @temporal-contract/client@0.0.1 build /home/runner/work/temporal-contract/temporal-contract/packages/client
+> tsdown src/index.ts --format cjs,esm --dts --clean
+
+ℹ tsdown v0.17.2 powered by rolldown v1.0.0-beta.53
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ [CJS] dist/index.cjs  8.38 kB │ gzip: 1.77 kB
+ℹ [CJS] 1 files, total: 8.38 kB
+ℹ [ESM] dist/index.mjs    8.12 kB │ gzip: 1.74 kB
+ℹ [ESM] dist/index.d.mts  6.70 kB │ gzip: 1.62 kB
+ℹ [ESM] 2 files, total: 14.81 kB
+✔ Build complete in 3603ms
+ℹ [CJS] dist/index.d.cts  6.70 kB │ gzip: 1.62 kB
+ℹ [CJS] 1 files, total: 6.70 kB
+✔ Build complete in 3605ms

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benoit TRAVERS
+
+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,98 @@
+# @temporal-contract/client
+
+> Type-safe client for consuming Temporal workflows
+
+## Installation
+
+```bash
+pnpm add @temporal-contract/client @temporal-contract/contract @temporalio/client zod
+```
+
+## Quick Start
+
+```typescript
+import { Connection } from '@temporalio/client';
+import { TypedClient } from '@temporal-contract/client';
+import { myContract } from './contract';
+
+// Connect to Temporal
+const connection = await Connection.connect({ address: 'localhost:7233' });
+
+// Create typed client
+const client = TypedClient.create(myContract, {
+  connection,
+  namespace: 'default',
+});
+
+// Execute workflow (fully typed!)
+const result = await client.executeWorkflow('processOrder', {
+  workflowId: 'order-123',
+  args: { orderId: 'ORD-123', customerId: 'CUST-456' },
+});
+
+console.log(result.status);  // 'success' | 'failed' — typed!
+```
+
+## API
+
+### `TypedClient.create(contract, options)`
+
+Creates a type-safe Temporal client.
+
+**Returns:** Type-safe client with these methods:
+
+#### `executeWorkflow(name, options)`
+
+Execute and wait for result:
+
+```typescript
+const result = await client.executeWorkflow('processOrder', {
+  workflowId: 'order-123',
+  args: { orderId: 'ORD-123', customerId: 'CUST-456' },
+});
+```
+
+#### `startWorkflow(name, options)` / `getHandle(name, workflowId)`
+
+Get a typed workflow handle for signals/queries/updates:
+
+```typescript
+const handle = await client.startWorkflow('processOrder', {
+  workflowId: 'order-456',
+  args: { orderId: 'ORD-456' },
+});
+
+// Type-safe queries, signals, updates
+await handle.queries.getStatus();
+await handle.signals.cancel({ reason: 'Customer request' });
+await handle.updates.changeAmount({ newAmount: 150 });
+```
+
+## Error Handling
+
+Custom error classes with contextual information:
+
+```typescript
+import { WorkflowValidationError, WorkflowNotFoundError } from '@temporal-contract/client';
+
+try {
+  await client.executeWorkflow('processOrder', { args: invalidData });
+} catch (error) {
+  if (error instanceof WorkflowValidationError) {
+    console.error('Validation:', error.zodError.errors);
+  } else if (error instanceof WorkflowNotFoundError) {
+    console.error('Available:', error.availableWorkflows);
+  }
+}
+```
+
+---
+
+## Learn More
+
+- [Main README](../../README.md) — Quick start guide
+- [Worker Implementation](../../docs/CONTRACT_HANDLER.md) — Implementing workers
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,269 @@
+let __temporalio_client = require("@temporalio/client");
+let zod = require("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 __temporalio_client.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 zod.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 zod.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 zod.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 zod.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 zod.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 zod.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 zod.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 zod.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 zod.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
+exports.QueryValidationError = QueryValidationError;
+exports.SignalValidationError = SignalValidationError;
+exports.TypedClient = TypedClient;
+exports.TypedClientError = TypedClientError;
+exports.UpdateValidationError = UpdateValidationError;
+exports.WorkflowNotFoundError = WorkflowNotFoundError;
+exports.WorkflowValidationError = WorkflowValidationError;

package/dist/index.d.cts

@@ -0,0 +1,190 @@
+import { ClientOptions, WorkflowHandle, WorkflowOptions, WorkflowStartOptions } from "@temporalio/client";
+import { ClientInferInput, ClientInferOutput, ClientInferWorkflowQueries, ClientInferWorkflowSignals, ClientInferWorkflowUpdates, ContractDefinition, WorkflowDefinition } from "@temporal-contract/contract";
+import { z } from "zod";
+
+//#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 };