Namecheap-ts

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

npm install namecheap-ts

yarn add namecheap-ts

pnpm add namecheap-ts

Quick Start

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:

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>

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[]>>

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>

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: "[email protected]",
  // ... 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>

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>

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>

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:

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

import { DomainPriceActions } from "namecheap-ts";

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

Error Handling

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

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
• API Method Reference
• GitHub Repository

License

ISC © Abdulrahman Kanakri

Contributing

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