namecheap-ts/README.md

A simple wrapper for namecheap API

# Namecheap-ts

[![npm version](https://img.shields.io/npm/v/namecheap-ts.svg)](https://www.npmjs.com/package/namecheap-ts)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

A modern TypeScript/JavaScript wrapper for the Namecheap API. Simplify domain management, registration, pricing, and account operations with full type safety.

## Features

✨ **Full TypeScript Support** - Complete type definitions for all methods and responses  
🎯 **Simple API** - Intuitive methods for common operations  
🔒 **Type-Safe** - Catch errors at compile time, not runtime  
🧪 **Sandbox Support** - Test your integration without affecting production  
📦 **Zero Config** - Works out of the box with ESM and CommonJS  
⚡ **Lightweight** - Minimal dependencies (axios, xml2js)

## Installation

```bash
npm install namecheap-ts
```

```bash
yarn add namecheap-ts
```

```bash
pnpm add namecheap-ts
```

## Quick Start

```typescript
import Namecheap, { INamecheapConfig } from "namecheap-ts";

// Configure the client
const config: INamecheapConfig = {
  apiUser: "your-api-username",
  apiKey: "your-api-key",
  username: "your-username",
  clientIp: "your-whitelisted-ip",
};

// Create an instance (set second parameter to true for sandbox)
const namecheap = new Namecheap(config, false);

// Check domain availability
const { data } = await namecheap.checkDomain("example.com");
console.log(`Available: ${data.available}, Premium: ${data.premium}`);
```

## Configuration

### INamecheapConfig

| Property   | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `apiUser`  | `string` | ✅       | Your Namecheap API username     |
| `apiKey`   | `string` | ✅       | Your Namecheap API key          |
| `username` | `string` | ✅       | Your Namecheap account username |
| `clientIp` | `string` | ✅       | Your whitelisted IP address     |

### Sandbox Mode

Pass `true` as the second parameter to use the Namecheap sandbox environment:

```typescript
const namecheap = new Namecheap(config, true); // Sandbox mode
```

## API Reference

### `checkDomain(domainName: string)`

Check if a domain is available for registration and whether it's a premium domain.

**Returns:** `Promise<ICheckDomainResponse>`

```typescript
const result = await namecheap.checkDomain("example.com");

if (result.data.available) {
  console.log("Domain is available!");
  if (result.data.premium) {
    console.log("This is a premium domain");
  }
}
```

### `getDomainPrice(domainName: string, action: DomainPriceAction)`

Get pricing information for a domain based on the action type.

**Parameters:**

- `domainName` - The domain name (e.g., "example.com")
- `action` - One of: `DomainPriceActions.REGISTER`, `RENEW`, `REACTIVATE`, `TRANSFER`

**Returns:** `Promise<IResponse<object[]>>`

```typescript
import { DomainPriceActions } from "namecheap-ts";

const pricing = await namecheap.getDomainPrice(
  "example.com",
  DomainPriceActions.REGISTER,
);

console.log(pricing.data);
```

### `registerDomain(payload: Payload)`

Register a new domain with Namecheap.

**Returns:** `Promise<IRegisterDomainResponse>`

```typescript
const payload = {
  DomainName: "example.com",
  Years: 1,
  // Add required registration fields according to Namecheap API docs
  RegistrantFirstName: "John",
  RegistrantLastName: "Doe",
  RegistrantAddress1: "123 Main St",
  RegistrantCity: "New York",
  RegistrantStateProvince: "NY",
  RegistrantPostalCode: "10001",
  RegistrantCountry: "US",
  RegistrantPhone: "+1.2125551234",
  RegistrantEmailAddress: "john@example.com",
  // ... additional required fields
};

const result = await namecheap.registerDomain(payload);
console.log(`Domain registered: ${result.data.domain}`);
console.log(`Order ID: ${result.data.orderID}`);
```

### `addFundsRequest(payload: AddFundsRequestPayload)`

Create a request to add funds to your Namecheap account.

**Returns:** `Promise<IAddFundsRequestResponse>`

```typescript
const payload = {
  username: "your-username",
  paymentType: "creditcard",
  amount: 100,
  returnURL: "https://yoursite.com/payment-complete",
};

const result = await namecheap.addFundsRequest(payload);
console.log(`Token ID: ${result.data.tokenId}`);
console.log(`Redirect to: ${result.data.redirectURL}`);
```

### `getFundsStatus(tokenId: string)`

Check the status of a funds request.

**Returns:** `Promise<IGetFundsStatusResponse>`

```typescript
const tokenId = "abc123-token-id";
const result = await namecheap.getFundsStatus(tokenId);

console.log(`Status: ${result.data.status}`);
console.log(`Amount: ${result.data.amount}`);
```

### `call(command: Command, payload: Payload)`

Make a direct API call to any Namecheap command.

**Returns:** `Promise<IResponse>`

```typescript
import { Commands } from "namecheap-ts";

const response = await namecheap.call(Commands.DOMAINS_CHECK, {
  DomainList: "example.com,test.com",
});

console.log(response.data);
```

## Type Definitions

### Available Commands

Import the `Commands` enum for type-safe command names:

```typescript
import { Commands } from "namecheap-ts";

// Examples:
Commands.DOMAINS_CHECK;
Commands.DOMAINS_CREATE;
Commands.USERS_GET_PRICING;
Commands.USERS_CREATE_ADD_FUNDS_REQUEST;
Commands.USERS_GET_ADD_FUNDS_STATUS;
```

### Domain Price Actions

```typescript
import { DomainPriceActions } from "namecheap-ts";

DomainPriceActions.REGISTER;
DomainPriceActions.RENEW;
DomainPriceActions.REACTIVATE;
DomainPriceActions.TRANSFER;
```

## Error Handling

```typescript
try {
  const result = await namecheap.checkDomain("example.com");
  console.log(result.data);
} catch (error) {
  if (error instanceof InvalidDomainNameException) {
    console.error("Invalid domain name provided");
  } else {
    console.error("API error:", error.message);
  }
}
```

## Complete Example

```typescript
import Namecheap, { INamecheapConfig, DomainPriceActions } from "namecheap-ts";

async function main() {
  const config: INamecheapConfig = {
    apiUser: process.env.NAMECHEAP_API_USER!,
    apiKey: process.env.NAMECHEAP_API_KEY!,
    username: process.env.NAMECHEAP_USERNAME!,
    clientIp: process.env.NAMECHEAP_CLIENT_IP!,
  };

  const namecheap = new Namecheap(config, true); // Sandbox mode

  // Check domain availability
  const domain = "example.com";
  const availabilityCheck = await namecheap.checkDomain(domain);

  if (availabilityCheck.data.available) {
    // Get pricing
    const pricing = await namecheap.getDomainPrice(
      domain,
      DomainPriceActions.REGISTER,
    );

    console.log("Domain is available!");
    console.log("Pricing:", pricing.data);
  } else {
    console.log("Domain is not available");
  }
}

main();
```

## Requirements

- Node.js 14 or higher
- A Namecheap account with API access enabled
- Whitelisted IP address for API access

## Getting API Credentials

1. Log in to your Namecheap account
2. Navigate to Profile → Tools → API Access
3. Enable API access and whitelist your IP address
4. Copy your API key and username

## Resources

- [Namecheap API Documentation](https://www.namecheap.com/support/api/intro/)
- [API Method Reference](https://www.namecheap.com/support/api/methods/)
- [GitHub Repository](https://github.com/abdulrahmanKanakri/namecheap-ts)

## License

ISC © Abdulrahman Kanakri

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.