Client & Connection Management

/**
 * High-level SDK client that aggregates sub-clients for different functionalities
 */
class Client {
  constructor(options: ClientOptions);

  /** WorkflowClient instance for workflow operations */
  readonly workflow: WorkflowClient;
  /** AsyncCompletionClient instance for manual activity completion */
  readonly activity: AsyncCompletionClient;
  /** ScheduleClient instance for schedule operations */
  readonly schedule: ScheduleClient;
  /** TaskQueueClient instance for task queue operations */
  readonly taskQueue: TaskQueueClient;
  /** Raw gRPC access to WorkflowService */
  readonly workflowService: WorkflowService;

  /** Execute function with deadline applied to all operations */
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
  /** Execute function with abort signal applied to all operations */
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
  /** Execute function with metadata applied to all operations */
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
}

interface ClientOptions {
  /** Connection to Temporal Server (optional, creates default if not provided) */
  connection?: ConnectionLike;
  /** Temporal namespace (default: 'default') */
  namespace?: string;
  /** Data converter for serialization (optional) */
  dataConverter?: DataConverter;
  /** Client interceptors for custom behavior */
  interceptors?: ClientInterceptors;
  /** Workflow client configuration */
  workflow?: {
    /** Should a query be rejected by closed and failed workflows */
    queryRejectCondition?: QueryRejectCondition;
  };
}

type LoadedClientOptions = Required<ClientOptions>;

import { Client, Connection } from "@temporalio/client";

// Basic client with default connection
const client = new Client();

// Client with custom connection
const connection = await Connection.connect({ address: 'temporal.example.com:7233' });
const client = new Client({
  connection,
  namespace: 'production',
});

// Using sub-clients
await client.workflow.start('myWorkflow', {
  args: ['arg1'],
  taskQueue: 'my-task-queue',
  workflowId: 'workflow-1',
});

// Context control - execute operation with deadline
await client.withDeadline(new Date(Date.now() + 30000), async () => {
  return await client.workflow.start('myWorkflow', options);
});

/**
 * Client connection to Temporal Server with gRPC service access
 */
class Connection {
  /** Create and verify connection to Temporal Server */
  static connect(options: ConnectionOptions): Promise<Connection>;
  /** Create lazy connection (connects on first use) */
  static lazy(options: ConnectionOptions): Connection;

  /** Ensure connection is established */
  ensureConnected(): Promise<void>;
  /** Close connection and cleanup resources */
  close(): Promise<void>;

  /** Execute function with deadline applied to requests */
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
  /** Execute function with abort signal applied to requests */
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
  /** Execute function with metadata applied to requests */
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
  /** Execute function with API key applied to requests */
  withApiKey<R>(apiKey: string, fn: () => Promise<R>): Promise<R>;
  /** Set persistent API key for all requests */
  setApiKey(apiKey: string): void;

  /** Raw gRPC access to WorkflowService */
  readonly workflowService: WorkflowService;
  /** Raw gRPC access to OperatorService */
  readonly operatorService: OperatorService;
  /** Raw gRPC access to TestService */
  readonly testService: TestService;
  /** Raw gRPC access to HealthService */
  readonly healthService: HealthService;
}

interface ConnectionOptions {
  /** Temporal Server address (default: 'localhost:7233') */
  address?: string;
  /** TLS configuration or boolean to enable TLS */
  tls?: TLSConfig | boolean;
  /** gRPC channel credentials */
  credentials?: ChannelCredentials;
  /** Call-level credentials */
  callCredentials?: CallCredentials[];
  /** gRPC channel arguments */
  channelArgs?: object;
  /** gRPC interceptors */
  interceptors?: Interceptor[];
  /** Default metadata for all requests */
  metadata?: Metadata;
  /** API key for Temporal Cloud */
  apiKey?: string;
  /** Connection timeout in milliseconds or duration string */
  connectTimeout?: string | number;
}

type ConnectionOptionsWithDefaults = ConnectionOptions & {
  address: string;
  tls: boolean | TLSConfig;
};

/** Default localhost target for local development */
const LOCAL_TARGET: string;

import { Connection, TLSConfig } from "@temporalio/client";

// Connect to local Temporal server
const connection = await Connection.connect();

// Connect to Temporal Cloud
const cloudConnection = await Connection.connect({
  address: 'namespace.account.tmprl.cloud:7233',
  tls: true,
  apiKey: 'your-api-key',
});

// Custom TLS configuration
const tlsConfig: TLSConfig = {
  clientCertPair: {
    crt: clientCert,
    key: clientKey,
  },
  serverNameOverride: 'temporal.example.com',
};

const secureConnection = await Connection.connect({
  address: 'temporal.example.com:7233',
  tls: tlsConfig,
});

// Lazy connection (connects on first use)
const lazyConnection = Connection.lazy({ address: 'remote-temporal:7233' });

// Connection with timeout
const timedConnection = await Connection.connect({
  address: 'temporal.example.com:7233',
  connectTimeout: '10s',
});

// Access raw gRPC services
const healthResponse = await connection.healthService.check({});

// Context control examples
await connection.withDeadline(new Date(Date.now() + 30000), async () => {
  return await connection.workflowService.getSystemInfo({});
});

await connection.withMetadata({ 'custom-header': 'value' }, async () => {
  return await connection.workflowService.describeNamespace({ name: 'default' });
});

await connection.withApiKey('api-key', async () => {
  return await connection.workflowService.listNamespaces({});
});

interface ConnectionLike {
  workflowService: WorkflowService;
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
}

/**
 * Base class for all client implementations
 */
class BaseClient {
  /** Underlying connection instance */
  readonly connection: ConnectionLike;

  /** Execute function with deadline applied to operations */
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
  /** Execute function with abort signal applied to operations */
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
  /** Execute function with metadata applied to operations */
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
}

interface BaseClientOptions {
  connection: ConnectionLike;
}

/** Default client configuration */
function defaultBaseClientOptions(): BaseClientOptions;

/** gRPC metadata mapping */
type Metadata = Record<string, string | Buffer | string[] | Buffer[]>;

/** gRPC call context */
interface CallContext {
  deadline?: Date;
  abortSignal?: AbortSignal;
}