Claude Code API Client TypeScript Guide: Build Type-Safe

Build a production-ready TypeScript API client for Claude Code by using compile-time type checking, IntelliSense support, and strong typing patterns. TypeScript ensures your integration catches errors at compile-time rather than runtime, enables confident refactoring, provides self-documenting code structure, and improves developer productivity through IDE support.

Why TypeScript for Claude Code Integration

TypeScript provides several advantages when working with Claude Code’s API:

Compile-time type checking catches errors before deployment
IntelliSense support in your IDE improves developer productivity
Self-documenting code reduces the need for external documentation
Refactoring confidence when making changes to your integration

Setting Up Your TypeScript Project

Begin by initializing a new TypeScript project with the necessary dependencies:

mkdir claude-code-api-client && cd claude-code-api-client
npm init -y
npm install typescript @types/node tsx -D

Create a tsconfig.json file with strict type checking enabled:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Defining Type-Safe API Types

Create a types file that defines all the request and response types for the Claude Code API:

// src/types.ts

export interface ClaudeCodeConfig {
  apiKey: string;
  baseUrl?: string;
  maxRetries?: number;
  timeout?: number;
}

export interface CompletionRequest {
  model: string;
  messages: Message[];
  maxTokens?: number;
  temperature?: number;
  stream?: boolean;
}

export interface Message {
  role: 'user' | 'assistant' | 'system';
  content: string;
}

export interface CompletionResponse {
  id: string;
  model: string;
  choices: Choice[];
  usage: Usage;
}

export interface Choice {
  message: Message;
  finishReason: string;
}

export interface Usage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}

Building the API Client Class

Create a reusable client class that handles authentication, request formatting, and error handling:

// src/client.ts

import { ClaudeCodeConfig, CompletionRequest, CompletionResponse } from './types.js';

export class ClaudeCodeClient {
  private apiKey: string;
  private baseUrl: string;
  private maxRetries: number;
  private timeout: number;

  constructor(config: ClaudeCodeConfig) {
    this.apiKey = config.apiKey;
    this.baseUrl = config.baseUrl ?? 'https://api.claude.ai/v1';
    this.maxRetries = config.maxRetries ?? 3;
    this.timeout = config.timeout ?? 30000;
  }

  async createCompletion(request: CompletionRequest): Promise<CompletionResponse> {
    const url = `${this.baseUrl}/chat/completions`;

    const response = await this.makeRequest(url, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(request),
    });

    return response as CompletionResponse;
  }

  private async makeRequest(url: string, options: RequestInit, attempt = 1): Promise<unknown> {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), this.timeout);

    try {
      const response = await fetch(url, {
        ...options,
        signal: controller.signal,
      });

      if (!response.ok) {
        const error = await response.json().catch(() => ({}));
        throw new ClaudeCodeError(
          error.message ?? `HTTP ${response.status}`,
          response.status,
          error
        );
      }

      return await response.json();
    } catch (error) {
      if (attempt < this.maxRetries && this.isRetryable(error)) {
        await this.delay(Math.pow(2, attempt) * 1000);
        return this.makeRequest(url, options, attempt + 1);
      }
      throw error;
    } finally {
      clearTimeout(timeoutId);
    }
  }

  private isRetryable(error: unknown): boolean {
    if (error instanceof ClaudeCodeError) {
      return error.status === 429 || error.status >= 500;
    }
    return false;
  }

  private delay(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

export class ClaudeCodeError extends Error {
  constructor(
    message: string,
    public status: number,
    public details?: unknown
  ) {
    super(message);
    this.name = 'ClaudeCodeError';
  }
}

Using the Client in Your Application

Here’s how to integrate the client into your TypeScript application:

// src/index.ts

import { ClaudeCodeClient } from './client.js';

const client = new ClaudeCodeClient({
  apiKey: process.env.CLAUDE_API_KEY ?? '',
  maxRetries: 3,
  timeout: 60000,
});

async function main() {
  try {
    const response = await client.createCompletion({
      model: 'claude-3-opus-20240229',
      messages: [
        { role: 'user', content: 'Explain TypeScript generics in simple terms' }
      ],
      maxTokens: 500,
      temperature: 0.7,
    });

    console.log(response.choices[0].message.content);
    console.log(`Total tokens used: ${response.usage.totalTokens}`);
  } catch (error) {
    if (error instanceof Error) {
      console.error(`Error: ${error.message}`);
    }
    process.exit(1);
  }
}

main();

Best Practices for Production Use

When deploying your TypeScript API client in production, consider these patterns:

1. Use dependency injection for testability

interface HttpClient {
  request(url: string, options: RequestInit): Promise<unknown>;
}

class ProductionHttpClient implements HttpClient {
  async request(url: string, options: RequestInit): Promise<unknown> {
    const response = await fetch(url, options);
    return response.json();
  }
}

2. Implement request caching for repeated queries

const cache = new Map<string, { data: unknown; timestamp: number }>();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedCompletion(key: string): Promise<unknown | null> {
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  return null;
}

3. Add structured logging

function logRequest(params: CompletionRequest): void {
  console.log(JSON.stringify({
    timestamp: new Date().toISOString(),
    model: params.model,
    tokens: params.maxTokens,
  }));
}

Publishing Your Client Library

When you’re ready to share your client with other developers, configure your package.json for npm publishing:

{
  "name": "claude-code-api-client",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsc",
    "test": "node --loader tsx test/index.ts"
  }
}

Using TypeScript Generics for Flexible Response Handling

The API client above uses a fixed response shape, but real-world applications often need to handle multiple response formats. TypeScript generics let you build a single method that infers the correct return type based on the request:

async request<TResponse>(
  endpoint: string,
  payload: CompletionRequest
): Promise<TResponse> {
  const response = await this.makeRequest(
    `${this.baseUrl}/${endpoint}`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    }
  );
  return response as TResponse;
}

// TypeScript infers the exact shape for each call
const completion = await client.request<CompletionResponse>('chat/completions', request);
const embedding = await client.request<EmbeddingResponse>('embeddings', embeddingRequest);

This pattern eliminates type assertions scattered throughout calling code and makes the client extensible without breaking existing consumers.

Validating Responses at Runtime with Zod

Compile-time types prevent mistakes in your code, but they cannot guard against API schema changes at runtime. Integrating Zod adds a runtime safety layer:

npm install zod

import { z } from 'zod';

const CompletionResponseSchema = z.object({
  id: z.string(),
  model: z.string(),
  choices: z.array(z.object({
    message: z.object({
      role: z.enum(['user', 'assistant', 'system']),
      content: z.string(),
    }),
    finishReason: z.string(),
  })),
  usage: z.object({
    promptTokens: z.number(),
    completionTokens: z.number(),
    totalTokens: z.number(),
  }),
});

async createCompletion(request: CompletionRequest): Promise<CompletionResponse> {
  const raw = await this.makeRequest(`${this.baseUrl}/chat/completions`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(request),
  });
  // Throws ZodError with field-level details if API changes its schema
  return CompletionResponseSchema.parse(raw);
}

When the API returns an unexpected field or changes a type, Zod throws a descriptive error immediately rather than silently passing malformed data further into your application. This is especially important in production systems where bugs from malformed API responses are difficult to trace.

Error Handling Patterns Worth Adopting

strong error handling distinguishes production-grade clients from prototype code. Beyond basic try/catch, consider these patterns:

Discriminated union results return a result type instead of throwing, letting callers decide how to handle failures:

type Result<T> =
  | { success: true; data: T }
  | { success: false; error: ClaudeCodeError };

async function safeCreateCompletion(
  client: ClaudeCodeClient,
  request: CompletionRequest
): Promise<Result<CompletionResponse>> {
  try {
    const data = await client.createCompletion(request);
    return { success: true, data };
  } catch (error) {
    if (error instanceof ClaudeCodeError) {
      return { success: false, error };
    }
    throw error;
  }
}

const result = await safeCreateCompletion(client, request);
if (result.success) {
  console.log(result.data.choices[0].message.content);
} else {
  console.error(`API error ${result.error.status}: ${result.error.message}`);
}

Context-enriched errors attach request metadata to thrown errors, so you can correlate errors with specific API calls in your monitoring dashboard:

throw new ClaudeCodeError(
  error.message ?? `HTTP ${response.status}`,
  response.status,
  { requestId: response.headers.get('x-request-id'), model: request.model }
);

This small addition means every error in your logs links back to the exact model and request that failed, dramatically reducing diagnosis time.

Building a type-safe TypeScript client for Claude Code ensures your integration handles edge cases gracefully while providing excellent developer experience through autocomplete and type hints.

Built by theluckystrike — More at zovo.one