CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TypeScript/JavaScript API client for the Retreaver Core API. This is an auto-generated OpenAPI client with manually written unit tests. The source code in

api/

models/

base.ts

common.ts

configuration.ts

, and

index.ts

is generated by OpenAPI Generator and should not be edited manually.

Development Commands

Building

npm run build          # Build both CommonJS (dist/) and ES modules (dist/esm/)
npm run prepare        # Same as build, runs automatically on install

Testing

npm test               # Run tests in watch mode
npm run test:run       # Run tests once
npm run test:coverage  # Run tests with coverage report
npm run test:ui        # Run tests with Vitest UI

Code Quality

npm run lint           # Lint TypeScript files
npm run lint:fix       # Auto-fix linting issues
npm run format         # Format code with Prettier
npm run format:check   # Check formatting without modifying
npm run typecheck      # Type check without building

Architecture

Code Generation

Generated files:

api/

models/

base.ts

common.ts

configuration.ts

Generated by OpenAPI Generator from Retreaver API spec
Do NOT edit these files directly - changes will be lost on regeneration
Files contain
```
/* tslint:disable */
```
and OpenAPI Generator headers

API Structure

Base classes:
```
BaseAPI
```
in
```
base.ts
```
handles Axios instance and configuration
API classes: Each resource (Calls, Affiliates, Targets, Campaigns, Numbers) has its own API class
Two-layer pattern: Each API class has:
1. ```
AxiosParamCreator
```
  - builds request parameters
2. ```
ApiFp
```
  - functional programming layer
3. ```
Api
```
  class - object-oriented wrapper extending
```
BaseAPI
```

Module Exports

Dual module format: CommonJS (
```
dist/
```
) and ES modules (
```
dist/esm/
```
)

Main entry point:

index.ts

exports from

api.ts

configuration.ts

, and

models/index.ts

TypeScript definitions included

Authentication

API key authentication via query parameter
```
api_key
```
Optional
```
company_id
```
parameter for multi-company access

Configuration pattern:

new Configuration({ apiKey: 'your_api_key' })

Testing Architecture

Framework: Vitest with globals enabled
Mocking: axios-mock-adapter for HTTP request mocking
Setup:
```
tests/setup/test-setup.ts
```
runs before tests

Mock utilities:

tests/mocks/http-mocks.ts

provides

setupHttpMocks()

mockGet()

verifyRequest()

Mock data:
```
tests/mocks/mock-data.ts
```
contains example API responses
Test pattern: Arrange-Act-Assert with HTTP mocking
Coverage threshold: 80% for branches, functions, lines, statements
Test files follow naming:
```
*.test.ts
```
in
```
tests/unit/
```
subdirectories

API Versioning

Calls API has two versions:
- V1:
```
/calls.json
```
  - legacy endpoint (
```
CallsApi
```
  )
- V2:
```
/api/v2/calls.json
```
  - enhanced with additional fields (
```
CallsV2Api
```
  )
Other endpoints use V1 URLs without version prefix

Important Conventions

When Writing Tests

Import from root level (
```
../../../api/...
```
, not relative within src)
Use mock utilities from
```
tests/mocks/http-mocks.ts
```
Mock data should match actual API response structure from Retreaver docs
Follow Arrange-Act-Assert pattern with comments
Always verify both response data and HTTP request parameters
Test error cases (404, 401) alongside success cases

When Adding Features

If modifying generated code is required, regenerate from OpenAPI spec instead
New functionality should be added as separate utilities, not modifications to generated files
Tests should be comprehensive with success and error cases
All new exports must be added to
```
index.ts
```
or
```
models/index.ts
```

Git Hooks

Pre-commit: Runs
```
lint-staged
```
(ESLint + Prettier on staged files)
Pre-push: Runs
```
npm run test:run
```
(all tests must pass)

Project Context

This client is published to npm as

@berrydev-ai/retreaver-api-client

and provides typed access to:

Call tracking data (V1 and V2 APIs)
Affiliate/publisher/source management
Target (destination phone number) configuration
Campaign routing and IVR settings
Phone number information

The API uses pagination (25 results per page via Link header) and supports both JSON and XML formats.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TypeScript/JavaScript API client for the Retreaver Core API. This is an auto-generated OpenAPI client with manually written unit tests. The source code in

api/

models/

base.ts

common.ts

configuration.ts

, and

index.ts

is generated by OpenAPI Generator and should not be edited manually.

Development Commands

Building

npm run build          # Build both CommonJS (dist/) and ES modules (dist/esm/)
npm run prepare        # Same as build, runs automatically on install

Testing

npm test               # Run tests in watch mode
npm run test:run       # Run tests once
npm run test:coverage  # Run tests with coverage report
npm run test:ui        # Run tests with Vitest UI

Code Quality

npm run lint           # Lint TypeScript files
npm run lint:fix       # Auto-fix linting issues
npm run format         # Format code with Prettier
npm run format:check   # Check formatting without modifying
npm run typecheck      # Type check without building

Architecture

Code Generation

Generated files:

api/

models/

base.ts

common.ts

configuration.ts

Generated by OpenAPI Generator from Retreaver API spec
Do NOT edit these files directly - changes will be lost on regeneration
Files contain
```
/* tslint:disable */
```
and OpenAPI Generator headers

API Structure

Base classes:
```
BaseAPI
```
in
```
base.ts
```
handles Axios instance and configuration
API classes: Each resource (Calls, Affiliates, Targets, Campaigns, Numbers) has its own API class
Two-layer pattern: Each API class has:
1. ```
AxiosParamCreator
```
  - builds request parameters
2. ```
ApiFp
```
  - functional programming layer
3. ```
Api
```
  class - object-oriented wrapper extending
```
BaseAPI
```

Module Exports

Dual module format: CommonJS (
```
dist/
```
) and ES modules (
```
dist/esm/
```
)

Main entry point:

index.ts

exports from

api.ts

configuration.ts

, and

models/index.ts

TypeScript definitions included

Authentication

API key authentication via query parameter
```
api_key
```
Optional
```
company_id
```
parameter for multi-company access

Configuration pattern:

new Configuration({ apiKey: 'your_api_key' })

Testing Architecture

Framework: Vitest with globals enabled
Mocking: axios-mock-adapter for HTTP request mocking
Setup:
```
tests/setup/test-setup.ts
```
runs before tests

Mock utilities:

tests/mocks/http-mocks.ts

provides

setupHttpMocks()

mockGet()

verifyRequest()

Mock data:
```
tests/mocks/mock-data.ts
```
contains example API responses
Test pattern: Arrange-Act-Assert with HTTP mocking
Coverage threshold: 80% for branches, functions, lines, statements
Test files follow naming:
```
*.test.ts
```
in
```
tests/unit/
```
subdirectories

API Versioning

Calls API has two versions:
- V1:
```
/calls.json
```
  - legacy endpoint (
```
CallsApi
```
  )
- V2:
```
/api/v2/calls.json
```
  - enhanced with additional fields (
```
CallsV2Api
```
  )
Other endpoints use V1 URLs without version prefix

Important Conventions

When Writing Tests

Import from root level (
```
../../../api/...
```
, not relative within src)
Use mock utilities from
```
tests/mocks/http-mocks.ts
```
Mock data should match actual API response structure from Retreaver docs
Follow Arrange-Act-Assert pattern with comments
Always verify both response data and HTTP request parameters
Test error cases (404, 401) alongside success cases

When Adding Features

If modifying generated code is required, regenerate from OpenAPI spec instead
New functionality should be added as separate utilities, not modifications to generated files
Tests should be comprehensive with success and error cases
All new exports must be added to
```
index.ts
```
or
```
models/index.ts
```

Git Hooks

Pre-commit: Runs
```
lint-staged
```
(ESLint + Prettier on staged files)
Pre-push: Runs
```
npm run test:run
```
(all tests must pass)

Project Context

This client is published to npm as

@berrydev-ai/retreaver-api-client

and provides typed access to:

Call tracking data (V1 and V2 APIs)
Affiliate/publisher/source management
Target (destination phone number) configuration
Campaign routing and IVR settings
Phone number information

The API uses pagination (25 results per page via Link header) and supports both JSON and XML formats.

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password