Public Wiki1,552View on GitHub
Want anthropics/anthropic-sdk-typescript knowledge in your AI?

src

The official Anthropic TypeScript/JavaScript SDK that provides programmatic access to Claude AI models. It includes the core SDK client plus specialized integrations for AWS Bedrock, Google Cloud Vertex AI, and Palantir Foundry, enabling developers to build AI-powered applications across multiple cloud platforms.

Tech Stack

JestTypeScriptZod

Key Features

  • Messages API Client
  • Streaming Support
  • Tool Runner Framework
  • Zod Schema Integration
  • AWS Bedrock Integration
  • Vertex AI Integration
  • Foundry Integration
  • Message Batching
  • MCP Protocol Support
  • Beta Files API

Entry Points

Start here when working with this codebase

SDK Client
src/client.ts

Main API client that orchestrates HTTP communication and provides unified interface for all API resources

Start here when adding new API methods, modifying request/response handling, or understanding how resources are wired together

Public API Exports
src/index.ts

Centralized public API aggregation - controls what gets exported from the SDK

Start here when adding new public types, classes, or functions that consumers should access

Resource Aggregation
src/resources.ts

Module aggregation for API resources - re-exports all resource modules

Start here when adding a new API resource category or understanding resource organization

Helpers Export
src/helpers/index.ts

Unified export interface for helper functions like Zod integration and JSON schema conversion

Start here when adding new helper utilities or schema validation features

Bedrock SDK Entry
packages/bedrock-sdk/jest.config.ts

AWS Bedrock integration package configuration

Start here when modifying Bedrock-specific functionality or AWS authentication

Vertex SDK Entry
packages/vertex-sdk/jest.config.ts

Google Cloud Vertex AI integration package configuration

Start here when modifying Vertex AI-specific functionality

Foundry SDK Entry
packages/foundry-sdk/jest.config.ts

Palantir Foundry integration with Azure AD auth

Start here when modifying Foundry-specific functionality or Azure authentication

How to Make Changes

Common modification patterns for this codebase

Add a new API endpoint/resource

1
src/resources/completions.ts

Create new resource file following this pattern - define types, create class extending APIResource, implement methods

Pattern: See how Completions class defines CompletionCreateParams interface and create() method with _client.post()

2
src/resources/models.ts

For resources with multiple operations (list, get, etc), follow this pattern with pagination

Pattern: See how Models class implements retrieve() and list() with PagePromise for paginated results

3
src/resources.ts

Export your new resource module - add export statement

Pattern: Add line like: export * from './resources/your-resource';

4
src/client.ts

Register resource on client - add property and instantiate in constructor

Pattern: See how 'messages: API.Messages' is declared and 'this.messages = new API.Messages(this)' in constructor

5
tests/api-resources/completions.test.ts

Create test file for new resource

Pattern: Follow test structure: mock client, test each method with expected params and response handling

Conventions to follow:

Resource classes extend base class and use _client for HTTP callsAll params interfaces end with 'Params' suffix (e.g., CompletionCreateParams)Use namespace pattern to group related types with the resource classPaginated endpoints return PagePromise with appropriate Page type

Add a new beta feature/resource

1
src/resources/beta/files.ts

Create beta resource file in beta directory

Pattern: See how Files class implements upload(), list(), delete(), download(), retrieveMetadata() methods

2
src/resources/beta/messages/messages.ts

For complex beta resources with sub-resources, follow nested structure

Pattern: See how Messages has 'batches: Batches' property for sub-resource access

3
tests/api-resources/beta/files.test.ts

Create test file in beta test directory

Pattern: Follow existing beta test patterns with proper mocking

Conventions to follow:

Beta features go in src/resources/beta/ directoryBeta endpoints use /beta/ prefix in API pathsBeta features may have different stability guarantees - document accordingly

Add a new helper/utility function

1
src/helpers/zod.ts

For schema-related helpers, add to or follow pattern in zod.ts

Pattern: See zodToJsonSchema() function that converts Zod schemas to JSON schema format

2
src/helpers/json-schema.ts

For JSON schema manipulation, add to json-schema.ts

Pattern: See how schemas are converted for Anthropic's structured output system

3
src/helpers/index.ts

Export new helper from index

Pattern: Add export statement to expose helper publicly

4
tests/resources/messages/parse.test.ts

Add tests for helper functionality

Pattern: See how structured output parsing is tested with mocked responses

Conventions to follow:

Helpers should be pure functions when possibleExport through src/helpers/index.ts for public accessUse TypeScript generics for type-safe schema handling

Add streaming functionality

1
src/lib/MessageStream.ts

Extend or follow MessageStream pattern for new streaming features

Pattern: See how MessageStream handles SSE parsing and event emission

2
examples/mcp.ts

Create example demonstrating streaming usage

Pattern: See how anthropic.beta.messages.stream() is used with async iteration

Conventions to follow:

Streaming methods return Stream objects that support async iterationUse SSE (Server-Sent Events) parsing from src/lib/Handle partial responses and accumulation properly

Add tool/function calling support

1
src/lib/tools/index.ts

Add tool definition or runner in tools module

Pattern: See existing tool execution framework structure

2
examples/tools-helpers-memory.ts

Create example showing tool integration

Pattern: See how beta memory tool integrates with filesystem backend and manages context

Conventions to follow:

Tools follow function calling pattern with input/output schemasUse Zod for tool parameter validation when possibleExamples should demonstrate complete tool lifecycle

Add a new example

1
examples/count-tokens.ts

Create example file following existing patterns

Pattern: See how count-tokens.ts demonstrates token counting with clear comments and error handling

2
examples/batch-results.ts

For batch/async operations, follow this pattern

Pattern: See how batch results are fetched and processed

Conventions to follow:

Examples should be self-contained and runnableInclude clear comments explaining each stepUse async/await for API callsHandle errors gracefully with try/catch

Add tests for existing functionality

1
tests/api-resources/messages/messages.test.ts

For API resource tests, follow this structure

Pattern: See how client is mocked, requests are tested with expected params, and responses are validated

2
tests/api-resources/messages/batches.test.ts

For resources with CRUD operations, test each method

Pattern: See tests for create, retrieve, list, delete, cancel operations

3
packages/bedrock-sdk/tests/client.test.ts

For SDK package tests, follow package-specific patterns

Pattern: See how Bedrock client tests mock fetch and validate request encoding

Conventions to follow:

Use Jest for all testsMock HTTP client rather than making real API callsTest both success and error casesValidate request parameters and response handling

Modify build/publish process

1
scripts/publish-packages.ts

Modify publishing logic for monorepo packages

Pattern: See how packages are published after releases

2
scripts/utils/postprocess-files.cjs

Modify build post-processing

Pattern: See how compiled output is cleaned and package exports are configured

Conventions to follow:

Build scripts use CommonJS (.cjs) for Node compatibilityPublishing handles monorepo package dependenciesPost-processing configures dual ESM/CJS exports

Coding Conventions

Standards and patterns used in this codebase

file-organization

Monorepo structure: apps/ contains deployable applications, packages/ contains shared libraries

Packages: packages/bedrock-sdk, packages/foundry-sdk, packages/vertex-sdk
packages/bedrock-sdkpackages/foundry-sdk
naming

File naming uses: kebab-case, PascalCase (for components/classes)

eslint.config.mjs, jest.config.ts, count-tokens.ts, tools-helpers-memory.ts, publish-packages.ts
eslint.config.mjsjest.config.tsexamples/count-tokens.ts
code-style

TypeScript is the primary language

All new files should be .ts or .tsx
jest.config.tsexamples/count-tokens.tsexamples/tools-helpers-memory.ts
testing

Tests use .test. pattern

Test files are named like component.test.ts or placed in __tests__/
tests/helpers/beta/mcp.test.tstests/lib/tools/ToolRunner.test.tstests/lib/tools/ToolRunnerE2E.test.ts
configuration

Configuration is centralized in config files

Config files: eslint.config.mjs, jest.config.ts
eslint.config.mjsjest.config.tspackages/bedrock-sdk/jest.config.ts
data-layer

Database operations are in data layer

Data files: src/helpers/json-schema.ts, src/lib/transform-json-schema.ts
src/helpers/json-schema.tssrc/lib/transform-json-schema.tssrc/helpers/beta/json-schema.ts
typescript

Types are defined in dedicated type files

Type files: src/internal/builtin-types.ts, src/internal/types.ts
src/internal/builtin-types.tssrc/internal/types.ts
utilities

Shared utilities are in utils/ directory

Utility files: scripts/utils/postprocess-files.cjs, src/helpers/index.ts
scripts/utils/postprocess-files.cjssrc/helpers/index.tssrc/helpers/json-schema.ts