Defining Contracts

Learn how to define type-safe contracts for your Temporal workflows and activities.

Overview

Contracts are the foundation of temporal-contract. They define the interface for your workflows, including inputs, outputs, and activities, all using Zod schemas for validation.

Basic Contract Structure

import { defineContract } from "@temporal-contract/contract";
import { z } from "zod";

export const myContract = defineContract({
  taskQueue: "my-task-queue",

  // Global activities available to all workflows
  activities: {
    log: {
      input: z.object({
        level: z.enum(["info", "warn", "error"]),
        message: z.string(),
      }),
      output: z.void(),
    },
  },

  // Workflow definitions
  workflows: {
    myWorkflow: {
      input: z.object({
        userId: z.string(),
        amount: z.number().positive(),
      }),
      output: z.object({
        success: z.boolean(),
        transactionId: z.string().optional(),
      }),

      // Workflow-specific activities
      activities: {
        processPayment: {
          input: z.object({
            userId: z.string(),
            amount: z.number(),
          }),
          output: z.object({
            transactionId: z.string(),
          }),
        },
      },
    },
  },
});

Contract Elements

Task Queue

The task queue name that workers will listen on:

taskQueue: "orders";

Global Activities

Activities that are available to all workflows in the contract:

activities: {
  sendEmail: {
    input: z.object({
      to: z.string().email(),
      subject: z.string(),
      body: z.string()
    }),
    output: z.object({ sent: z.boolean() }),
  },
}

Workflows

Each workflow must define:

• input: Zod schema for workflow parameters
• output: Zod schema for workflow return value
• activities: Workflow-specific activities (optional)

workflows: {
  processOrder: {
    input: z.object({ orderId: z.string() }),
    output: z.object({ status: z.string() }),
    activities: { /* ... */ }
  }
}

Workflow-Specific Activities

Activities that are only available within a specific workflow:

workflows: {
  processOrder: {
    // ...
    activities: {
      chargeCard: {
        input: z.object({ amount: z.number() }),
        output: z.object({ success: z.boolean() }),
      },
    },
  },
}

Schema Validation

All inputs and outputs are validated using Zod schemas:

input: z.object({
  email: z.string().email(), // Email validation
  age: z.number().int().positive(), // Integer validation
  status: z.enum(["active", "inactive"]), // Enum validation
  metadata: z.record(z.string()).optional(), // Optional fields
});

Type Inference

TypeScript automatically infers types from your schemas:

const contract = defineContract({
  workflows: {
    processOrder: {
      input: z.object({
        orderId: z.string(),
        amount: z.number(),
      }),
      output: z.object({
        success: z.boolean(),
      }),
      activities: {},
    },
  },
});

// Types are automatically inferred:
// input: { orderId: string; amount: number }
// output: { success: boolean }

Complex Schemas

Use Zod's full power for complex validations:

const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zipCode: z.string().regex(/^\d{5}$/),
});

const OrderSchema = z.object({
  items: z
    .array(
      z.object({
        productId: z.string(),
        quantity: z.number().int().positive(),
      }),
    )
    .min(1),
  shippingAddress: AddressSchema,
  billingAddress: AddressSchema.optional(),
  total: z.number().positive(),
});

export const orderContract = defineContract({
  taskQueue: "orders",
  workflows: {
    processOrder: {
      input: OrderSchema,
      output: z.object({
        orderId: z.string(),
        status: z.enum(["pending", "completed", "failed"]),
      }),
      activities: {},
    },
  },
});

Reusable Schemas

Define schemas once and reuse them:

const PaymentInput = z.object({
  amount: z.number().positive(),
  currency: z.enum(["USD", "EUR", "GBP"]),
});

const PaymentOutput = z.object({
  transactionId: z.string(),
  status: z.enum(["success", "failed"]),
});

export const contract = defineContract({
  taskQueue: "payments",
  workflows: {
    processPayment: {
      input: PaymentInput,
      output: PaymentOutput,
      activities: {
        chargeCard: {
          input: PaymentInput,
          output: PaymentOutput,
        },
      },
    },
  },
});

Multiple Workflows

A contract can define multiple workflows:

export const ecommerceContract = defineContract({
  taskQueue: "ecommerce",
  workflows: {
    processOrder: {
      input: z.object({ orderId: z.string() }),
      output: z.object({ success: z.boolean() }),
      activities: {
        /* ... */
      },
    },
    processRefund: {
      input: z.object({ orderId: z.string(), reason: z.string() }),
      output: z.object({ refunded: z.boolean() }),
      activities: {
        /* ... */
      },
    },
    updateInventory: {
      input: z.object({ productId: z.string(), delta: z.number() }),
      output: z.object({ newQuantity: z.number() }),
      activities: {
        /* ... */
      },
    },
  },
});

Best Practices

1. Keep Contracts Focused

Group related workflows in the same contract:

// ✅ Good - related workflows together
export const orderContract = defineContract({
  taskQueue: "orders",
  workflows: {
    createOrder: {
      /* ... */
    },
    cancelOrder: {
      /* ... */
    },
    updateOrder: {
      /* ... */
    },
  },
});

// ❌ Avoid - mixing unrelated workflows
export const contract = defineContract({
  taskQueue: "everything",
  workflows: {
    processOrder: {
      /* ... */
    },
    sendEmail: {
      /* ... */
    },
    generateReport: {
      /* ... */
    },
  },
});

2. Use Descriptive Names

// ✅ Good - clear and descriptive
workflows: {
  processOrderPayment: { /* ... */ },
  cancelOrderAndRefund: { /* ... */ },
}

// ❌ Avoid - vague names
workflows: {
  process: { /* ... */ },
  handle: { /* ... */ },
}

3. Document Complex Schemas

/**
 * Order processing workflow
 *
 * Handles the complete order lifecycle including:
 * - Payment processing
 * - Inventory reservation
 * - Shipping coordination
 */
processOrder: {
  input: z.object({
    orderId: z.string().describe('Unique order identifier'),
    customerId: z.string().describe('Customer UUID'),
    items: z.array(OrderItemSchema).describe('List of items to purchase'),
  }),
  // ...
}

See Also

• Client Usage - Using contracts with the client
• Worker Usage - Implementing contracts in workers
• Core Concepts - Understanding the contract-first approach