> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.dental/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Official TypeScript SDK with type-safe access to the API Dental platform, full IntelliSense support, and automatic retries.

Our official TypeScript SDK provides type-safe access to the API Dental platform with full IntelliSense support.

<CardGroup cols={2}>
  <Card icon="github" href="https://github.com/api-dental/api-dental-typescript-sdk" title="GitHub Repository">
    View source code and contribute
  </Card>

  <Card icon="box" href="https://www.npmjs.com/package/api-dental" title="NPM Package">
    api-dental on npm
  </Card>
</CardGroup>

## Installation

```bash theme={null}
npm install api-dental
```

## Usage

```typescript theme={null}
import APIDentalPro from 'api-dental';

const client = new APIDentalPro({
  apiKey: process.env['API_DENTAL_API_KEY'],
});

const response = await client.eligibility.request({
  payer: { id: '52133' },
  provider: { npi: '1447364856', tax_id: '270872579' },
  subscriber: {
    first_name: 'John',
    last_name: 'Smith',
    member_id: '123456789',
    group_number: 'GRP001',
    dob: '01/15/1990',
  },
  version: 'v2',
});
```

## Available Methods

| Method | Description |
| - | - |
| `client.eligibility.request({ ... })` | Request eligibility verification |
| `client.clearCoverage.request({ ... })` | Request ClearCoverage verification |
| `client.payer.list()` | List all supported payers |

## Request & Response Types

The SDK includes TypeScript definitions for all request params and response fields:

```typescript theme={null}
import APIDentalPro from 'api-dental';

const params: APIDentalPro.EligibilityRequestParams = {
  payer: { id: '52133' },
  provider: { npi: '1447364856', tax_id: '270872579' },
  subscriber: {
    dob: '01/15/1990',
    first_name: 'John',
    group_number: 'GRP001',
    last_name: 'Smith',
    member_id: '123456789',
  },
  version: 'v2',
};

const response: unknown = await client.eligibility.request(params);
```

## Error Handling

When the API returns a non-success status code, a subclass of `APIError` is thrown:

```typescript theme={null}
const response = await client.eligibility
  .request({ /* ... */ })
  .catch(async (err) => {
    if (err instanceof APIDentalPro.APIError) {
      console.log(err.status);  // 400
      console.log(err.name);    // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
```

| Status Code | Error Type |
| - | - |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| >= 500 | `InternalServerError` |
| N/A | `APIConnectionError` |

## Retries

Certain errors are automatically retried 2 times by default with exponential backoff. Connection errors, 408, 409, 429, and >= 500 errors are retried.

```typescript theme={null}
// Configure the default for all requests:
const client = new APIDentalPro({
  maxRetries: 0, // default is 2
});

// Or configure per-request:
await client.eligibility.request({ /* ... */ }, {
  maxRetries: 5,
});
```

## Timeouts

Requests time out after 1 minute by default:

```typescript theme={null}
// Configure the default for all requests:
const client = new APIDentalPro({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.eligibility.request({ /* ... */ }, {
  timeout: 5 * 1000,
});
```

<Tip>
  For ClearCoverage requests, consider increasing the timeout to 120 seconds as enriched eligibility queries may take longer to process.
</Tip>

## Accessing Raw Response Data

```typescript theme={null}
// Get raw Response (headers only, body not consumed)
const response = await client.eligibility
  .request({ /* ... */ })
  .asResponse();
console.log(response.headers.get('X-My-Header'));

// Get parsed data + raw Response together
const { data, response: raw } = await client.eligibility
  .request({ /* ... */ })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(data);
```

## Logging

```typescript theme={null}
const client = new APIDentalPro({
  logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error' | 'off'
});
```

Custom loggers are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), and [consola](https://www.npmjs.com/package/consola):

```typescript theme={null}
import pino from 'pino';

const client = new APIDentalPro({
  logger: pino().child({ name: 'APIDentalPro' }),
  logLevel: 'debug',
});
```

## Requirements

* TypeScript >= 4.9
* Node.js 20 LTS or later
* Deno v1.28.0+
* Bun 1.0+
* Cloudflare Workers
* Vercel Edge Runtime