{"_id":"@apiclient.xyz/namecheap","name":"@apiclient.xyz/namecheap","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@apiclient.xyz/namecheap","version":"1.0.2","private":false,"description":"unofficial namecheap API client","main":"dist_ts/index.js","typings":"dist_ts/index.d.ts","type":"module","author":{"name":"Task Venture Capital GmbH"},"license":"MIT","devDependencies":{"@git.zone/tsbuild":"^2.1.25","@git.zone/tsbundle":"^2.0.5","@git.zone/tsrun":"^1.2.46","@git.zone/tstest":"^1.0.44","@push.rocks/tapbundle":"^5.0.15","@types/node":"^20.8.7"},"dependencies":{"@push.rocks/qenv":"^6.1.0","@push.rocks/smartpath":"^5.0.18","@types/xml2js":"^0.4.14","axios":"^1.8.4","xml2js":"^0.6.2"},"repository":{"type":"git","url":"https://code.foss.global/apiclient.xyz/namecheap.git"},"bugs":{"url":"https://code.foss.global/apiclient.xyz/namecheap/issues"},"homepage":"https://code.foss.global/apiclient.xyz/namecheap#readme","scripts":{"test":"(tstest test/ --web)","build":"(tsbuild --web --allowimplicitany)","buildDocs":"(tsdoc)"},"_id":"@apiclient.xyz/namecheap@1.0.2","_integrity":"sha512-EOlJzydqn+vBFvodxxltxbaqCyaHiTVhwoDrpJH9bIQh/jLjH7wFR79hR8HAMklkoIgXIqq7ljT/J+TWy5aAFw==","_resolved":"/tmp/8f7b35f65adf8635caa841f21744b112/apiclient.xyz-namecheap-1.0.2.tgz","_from":"file:apiclient.xyz-namecheap-1.0.2.tgz","_nodeVersion":"23.8.0","_npmVersion":"11.2.0","dist":{"integrity":"sha512-EOlJzydqn+vBFvodxxltxbaqCyaHiTVhwoDrpJH9bIQh/jLjH7wFR79hR8HAMklkoIgXIqq7ljT/J+TWy5aAFw==","shasum":"6d99158dea88111b53e43b665bd8545f3b7efaef","tarball":"https://registry.npmjs.org/@apiclient.xyz/namecheap/-/namecheap-1.0.2.tgz","fileCount":37,"unpackedSize":213720,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDu0+3KL5Kb+e9sx45z/SsXVwoB5E5G8sXLuYtNJ+1VlwIhAJVV4WUJrXJLOiE60GLZqseFtTXmylKz3OLgfzIaCc3u"}]},"_npmUser":{"name":"lossless","email":"hello@lossless.com"},"directories":{},"maintainers":[{"name":"lossless","email":"hello@lossless.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/namecheap_1.0.2_1743607302857_0.8069672686086153"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-02T15:21:42.752Z","1.0.2":"2025-04-02T15:21:43.068Z","modified":"2025-04-02T15:21:43.362Z"},"maintainers":[{"name":"lossless","email":"hello@lossless.com"}],"description":"unofficial namecheap API client","homepage":"https://code.foss.global/apiclient.xyz/namecheap#readme","repository":{"type":"git","url":"https://code.foss.global/apiclient.xyz/namecheap.git"},"author":{"name":"Task Venture Capital GmbH"},"bugs":{"url":"https://code.foss.global/apiclient.xyz/namecheap/issues"},"license":"MIT","readme":"# Namecheap API Client\n\nA comprehensive TypeScript client for the Namecheap API, providing a clean, type-safe interface for domain management, DNS configuration, and domain transfers.\n\n## Features\n\n- **Complete API Coverage**: Supports all major Namecheap API endpoints\n- **Type Safety**: Full TypeScript definitions for all API requests and responses\n- **Error Handling**: Comprehensive error handling with detailed error messages\n- **Sandbox Support**: Test your integration with the Namecheap sandbox environment\n- **Modular Design**: Organized into logical modules for different API functionalities\n\n## Installation\n\n```bash\n# Using npm\nnpm install @apiclient.xyz/namecheap\n\n# Using yarn\nyarn add @apiclient.xyz/namecheap\n\n# Using pnpm\npnpm add @apiclient.xyz/namecheap\n```\n\n## Quick Start\n\n```typescript\nimport { NamecheapClient } from '@apiclient.xyz/namecheap';\n\n// Create a new client instance\nconst client = new NamecheapClient({\n  apiUser: 'your-api-username',\n  apiKey: 'your-api-key',\n  userName: 'your-username', // Often the same as apiUser\n  clientIp: 'your-ip-address'\n}, true); // true for sandbox mode, false for production\n\n// Check if a domain is available\nconst availability = await client.domains.check('example.com');\nconsole.log(`Domain is ${availability[0].available ? 'available' : 'not available'}`);\n\n// Get a list of domains in your account\nconst domainList = await client.domains.getList();\nconsole.log(`You have ${domainList.domains.length} domains`);\n```\n\n## API Documentation\n\n### Client Initialization\n\n```typescript\n// Create a client for production use\nconst productionClient = new NamecheapClient({\n  apiUser: 'your-api-username',\n  apiKey: 'your-api-key',\n  userName: 'your-username',\n  clientIp: 'your-ip-address'\n});\n\n// Create a client for sandbox testing\nconst sandboxClient = new NamecheapClient({\n  apiUser: 'your-api-username',\n  apiKey: 'your-api-key',\n  userName: 'your-username',\n  clientIp: 'your-ip-address'\n}, true);\n\n// Switch between sandbox and production\nclient.enableSandbox(); // Switch to sandbox\nclient.disableSandbox(); // Switch to production\n\n// Set request timeout (in milliseconds)\nclient.setTimeout(30000); // 30 seconds\n```\n\n### Domain Management\n\n#### Check Domain Availability\n\n```typescript\n// Check a single domain\nconst singleResult = await client.domains.check('example.com');\nconsole.log(`Domain is ${singleResult[0].available ? 'available' : 'not available'}`);\n\n// Check multiple domains\nconst multipleResults = await client.domains.check(['example.com', 'example.org', 'example.net']);\nmultipleResults.forEach(result => {\n  console.log(`${result.domain} is ${result.available ? 'available' : 'not available'}`);\n\n  if (result.isPremium) {\n    console.log(`Premium domain: Registration price: ${result.premiumRegistrationPrice}`);\n  }\n});\n```\n\n#### Get Domain List\n\n```typescript\n// Get all domains\nconst allDomains = await client.domains.getList();\n\n// Get with pagination\nconst page2 = await client.domains.getList({\n  Page: 2,\n  PageSize: 20\n});\n\n// Filter domains\nconst expiringDomains = await client.domains.getList({\n  ListType: 'EXPIRING'\n});\n\n// Search domains\nconst searchResults = await client.domains.getList({\n  SearchTerm: 'example'\n});\n\n// Sort domains\nconst sortedDomains = await client.domains.getList({\n  SortBy: 'EXPIREDATE_DESC'\n});\n```\n\n#### Get Domain Information\n\n```typescript\n// Get detailed information about a domain\nconst domainInfo = await client.domains.getInfo('example.com');\n\nconsole.log(`Domain: ${domainInfo.domainName}`);\nconsole.log(`Created: ${domainInfo.createdDate}`);\nconsole.log(`Expires: ${domainInfo.expiredDate}`);\nconsole.log(`WhoisGuard: ${domainInfo.whoisGuard.enabled ? 'Enabled' : 'Disabled'}`);\n```\n\n#### Domain Contact Management\n\n```typescript\n// Get contact information for a domain\nconst contacts = await client.domains.getContacts('example.com');\n\nconsole.log('Registrant:', contacts.registrant);\nconsole.log('Technical Contact:', contacts.tech);\nconsole.log('Admin Contact:', contacts.admin);\nconsole.log('Billing Contact:', contacts.auxBilling);\n\n// Update contact information\nconst updatedContacts = {\n  registrant: {\n    FirstName: 'John',\n    LastName: 'Doe',\n    Address1: '123 Main St',\n    City: 'Anytown',\n    StateProvince: 'CA',\n    PostalCode: '12345',\n    Country: 'US',\n    Phone: '+1.5555555555',\n    EmailAddress: 'john.doe@example.com'\n  },\n  // You can update any or all contact types\n  tech: { /* ... */ },\n  admin: { /* ... */ },\n  auxBilling: { /* ... */ }\n};\n\nconst success = await client.domains.setContacts('example.com', updatedContacts);\n```\n\n#### Register a Domain\n\n```typescript\n// Register a new domain\nconst registrationResult = await client.domains.create({\n  domainName: 'example.com',\n  years: 1,\n  contacts: {\n    registrant: {\n      FirstName: 'John',\n      LastName: 'Doe',\n      Address1: '123 Main St',\n      City: 'Anytown',\n      StateProvince: 'CA',\n      PostalCode: '12345',\n      Country: 'US',\n      Phone: '+1.5555555555',\n      EmailAddress: 'john.doe@example.com'\n    },\n    tech: { /* Same structure as registrant */ },\n    admin: { /* Same structure as registrant */ },\n    auxBilling: { /* Same structure as registrant */ }\n  },\n  nameservers: ['dns1.namecheaphosting.com', 'dns2.namecheaphosting.com'],\n  addFreeWhoisguard: true,\n  whoisguardPrivacy: true\n});\n\nconsole.log(`Domain registered: ${registrationResult.domain}`);\nconsole.log(`Order ID: ${registrationResult.orderId}`);\n```\n\n#### Renew a Domain\n\n```typescript\n// Renew a domain registration\nconst renewalResult = await client.domains.renew('example.com', 1);\n\nconsole.log(`Domain renewed: ${renewalResult.domainName}`);\nconsole.log(`New expiry date: ${renewalResult.expireDate}`);\n```\n\n#### Reactivate an Expired Domain\n\n```typescript\n// Reactivate an expired domain\nconst reactivationResult = await client.domains.reactivate('example.com');\n\nconsole.log(`Domain reactivated: ${reactivationResult.domain}`);\nconsole.log(`Order ID: ${reactivationResult.orderId}`);\n```\n\n#### Registrar Lock Management\n\n```typescript\n// Get the registrar lock status\nconst isLocked = await client.domains.getRegistrarLock('example.com');\nconsole.log(`Domain is ${isLocked ? 'locked' : 'unlocked'}`);\n\n// Set the registrar lock status\nawait client.domains.setRegistrarLock('example.com', true); // Lock the domain\nawait client.domains.setRegistrarLock('example.com', false); // Unlock the domain\n```\n\n#### Get Available TLDs\n\n```typescript\n// Get a list of available TLDs\nconst tlds = await client.domains.getTldList();\nconsole.log(`Available TLDs: ${tlds.join(', ')}`);\n```\n\n### DNS Management\n\n#### Get DNS Host Records\n\n```typescript\n// Get all DNS records for a domain\nconst hostRecords = await client.dns.getHosts('example.com');\n\nhostRecords.forEach(record => {\n  console.log(`${record.name} (${record.type}): ${record.address} (TTL: ${record.ttl})`);\n});\n```\n\n#### Set DNS Host Records\n\n```typescript\n// Set DNS records for a domain\nconst newRecords = [\n  {\n    hostName: '@',\n    recordType: 'A',\n    address: '192.0.2.1',\n    ttl: 300\n  },\n  {\n    hostName: 'www',\n    recordType: 'CNAME',\n    address: '@',\n    ttl: 300\n  },\n  {\n    hostName: 'mail',\n    recordType: 'MX',\n    address: 'mail.example.com',\n    mxPref: 10,\n    ttl: 300\n  }\n];\n\nconst success = await client.dns.setHosts('example.com', newRecords);\n```\n\n#### Set Custom Nameservers\n\n```typescript\n// Set custom nameservers for a domain\nconst nameservers = [\n  'ns1.example.com',\n  'ns2.example.com'\n];\n\nconst success = await client.dns.setCustom('example.com', nameservers);\n```\n\n#### Email Forwarding\n\n```typescript\n// Get email forwarding settings\nconst forwardings = await client.dns.getEmailForwarding('example.com');\n\nforwardings.forEach(forward => {\n  console.log(`${forward.from}@example.com → ${forward.to}`);\n});\n\n// Set email forwarding\nconst newForwardings = [\n  {\n    from: 'info',\n    to: 'your-email@gmail.com'\n  },\n  {\n    from: 'sales',\n    to: 'sales@company.com'\n  }\n];\n\nconst success = await client.dns.setEmailForwarding('example.com', newForwardings);\n```\n\n#### Get DNS Servers\n\n```typescript\n// Get a list of DNS servers for a domain\nconst dnsServers = await client.dns.getList('example', 'com');\nconsole.log(`DNS Servers: ${dnsServers.join(', ')}`);\n```\n\n### Nameserver Management\n\n#### Create a Nameserver\n\n```typescript\n// Create a new nameserver\nconst success = await client.ns.create(\n  'example', // SLD (Second-Level Domain)\n  'com',     // TLD (Top-Level Domain)\n  'ns1.example.com', // Nameserver hostname\n  '192.0.2.1' // IP address\n);\n```\n\n#### Delete a Nameserver\n\n```typescript\n// Delete a nameserver\nconst success = await client.ns.delete(\n  'example', // SLD\n  'com',     // TLD\n  'ns1.example.com' // Nameserver hostname\n);\n```\n\n#### Get Nameserver Information\n\n```typescript\n// Get information about a nameserver\nconst nsInfo = await client.ns.getInfo(\n  'example', // SLD\n  'com',     // TLD\n  'ns1.example.com' // Nameserver hostname\n);\n\nconsole.log(`Nameserver: ${nsInfo.nameserver}`);\nconsole.log(`IP: ${nsInfo.ip}`);\nconsole.log(`Statuses: ${nsInfo.statuses.join(', ')}`);\n```\n\n#### Update a Nameserver\n\n```typescript\n// Update a nameserver's IP address\nconst success = await client.ns.update(\n  'example', // SLD\n  'com',     // TLD\n  'ns1.example.com', // Nameserver hostname\n  '192.0.2.1', // Old IP address\n  '192.0.2.2'  // New IP address\n);\n```\n\n### Domain Transfers\n\n#### Get Transfer List\n\n```typescript\n// Get a list of domain transfers\nconst transfers = await client.transfer.getList();\n\ntransfers.transfers.forEach(transfer => {\n  console.log(`${transfer.domainName} (Status: ${transfer.status})`);\n});\n\n// With pagination\nconst page2 = await client.transfer.getList(2, 20);\n\n// Filter by status\nconst inProgress = await client.transfer.getList(1, 20, 'INPROGRESS');\n```\n\n#### Get Transfer Status\n\n```typescript\n// Get the status of a specific transfer\nconst status = await client.transfer.getStatus(12345); // Transfer ID\n\nconsole.log(`Domain: ${status.domainName}`);\nconsole.log(`Status: ${status.status}`);\nconsole.log(`Description: ${status.statusDescription}`);\n```\n\n#### Create a Transfer\n\n```typescript\n// Initiate a domain transfer to Namecheap\nconst transferResult = await client.transfer.create(\n  'example.com', // Domain name\n  1, // Number of years to renew for\n  'AUTH_CODE', // Authorization code from current registrar\n  {\n    addFreeWhoisguard: true,\n    whoisguardEnable: true\n  }\n);\n\nconsole.log(`Transfer initiated: ${transferResult.transferId}`);\nconsole.log(`Status: ${transferResult.transferStatus}`);\n```\n\n#### Update Transfer Status\n\n```typescript\n// Update the status of a transfer (e.g., to resubmit)\nconst success = await client.transfer.updateStatus(12345, true); // Transfer ID, resubmit flag\n```\n\n#### Get Transfer Information\n\n```typescript\n// Get detailed information about a transfer\nconst transferInfo = await client.transfer.getInfo(12345); // Transfer ID\n\nconsole.log(`Domain: ${transferInfo.domainName}`);\nconsole.log(`Status: ${transferInfo.status}`);\nconsole.log(`Order Date: ${transferInfo.orderDate}`);\nconsole.log(`WhoisGuard Status: ${transferInfo.whoisguardStatus}`);\n```\n\n## Error Handling\n\nThe client provides detailed error messages for API errors:\n\n```typescript\ntry {\n  await client.domains.getInfo('example.com');\n} catch (error) {\n  console.error('API Error:', error.message);\n\n  // For more detailed error information\n  if (error.errors) {\n    error.errors.forEach(err => console.error(' - ', err));\n  }\n}\n```\n\n## Sandbox Testing\n\nNamecheap provides a sandbox environment for testing API integrations. To use it:\n\n1. Register for a sandbox account at [https://www.sandbox.namecheap.com/](https://www.sandbox.namecheap.com/)\n2. Enable API access in your sandbox account\n3. Get your API key from the profile settings\n4. Whitelist your IP address in the API settings\n5. Create a client with sandbox mode enabled:\n\n```typescript\nconst client = new NamecheapClient({\n  apiUser: 'your-sandbox-username',\n  apiKey: 'your-sandbox-api-key',\n  userName: 'your-sandbox-username',\n  clientIp: 'your-whitelisted-ip'\n}, true); // true enables sandbox mode\n```\n\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.","readmeFilename":"readme.md","_rev":"1-ef84c4922789436f0a368847ec240f1b"}