// File: lib/clients/namecomclient/readme.md

namecomclient

This library provides a client for interacting with the Name.com API v4.

Configuration

You can configure the client using a HeroScript file:

!!namecomclient.configure
    name: 'default' // optional, 'default' is the default instance name
    url: 'https://api.name.com'  // production URL, use 'https://api.dev.name.com' for sandbox
    username: 'your-username'
    token: 'your-api-token'

Usage Example

Here's how to get the client and use its methods.

import incubaid.herolib.clients.namecomclient
import incubaid.herolib.core.base

fn main() ! {
    // Make sure hero is initialized
    base.init()!

    // Example configuration (can also be loaded from file)
    heroscript_config := '!!namecomclient.configure url:'https://api.name.com' username:'myuser' token:'...your_token...''
    mut plbook := playbook.new(text: heroscript_config)!
    namecomclient.play(mut plbook)!

    // Get the default configured client
    mut client := namecomclient.get()!

    // Test connection
    hello := client.hello()!
    println('Connected as: ${hello.username}')

    // List all domains
    domains := client.list_domains()!
    println('Found ${domains.len} domains:')
    for domain in domains {
        println('- ${domain.domain_name} (expires: ${domain.expire_date})')
    }

    // Get DNS records for a domain
    records := client.list_records('example.com')!
    println('Found ${records.len} DNS records:')
    for record in records {
        println('  ${record.host}.${record.domain_name} ${record.record_type} ${record.answer}')
    }

    // Create a new A record
    new_record := client.create_record('example.com', namecomclient.CreateRecordRequest{
        host: 'www'
        record_type: 'A'
        answer: '10.0.0.1'
        ttl: 300
    })!
    println('Created record with ID: ${new_record.id}')

    // Check domain availability
    results := client.check_availability(['example.org', 'example.net'])!
    for result in results {
        status := if result.purchasable { 'available' } else { 'taken' }
        println('${result.domain_name}: ${status}')
    }
}

API Reference

Domain Operations

• list_domains() - List all domains in the account
• get_domain(domain_name) - Get details for a specific domain
• lock_domain(domain_name) - Lock a domain to prevent transfers
• unlock_domain(domain_name) - Unlock a domain to allow transfers
• enable_autorenew(domain_name) - Enable auto-renewal
• disable_autorenew(domain_name) - Disable auto-renewal
• enable_whois_privacy(domain_name) - Enable WHOIS privacy
• disable_whois_privacy(domain_name) - Disable WHOIS privacy
• set_nameservers(domain_name, nameservers) - Set nameservers for a domain
• set_contacts(domain_name, contacts) - Set contacts for a domain
• check_availability(domain_names) - Check if domains are available
• search(keyword) - Search for available domains

DNS Record Operations

• list_records(domain_name) - List all DNS records for a domain
• get_record(domain_name, record_id) - Get a specific DNS record
• create_record(domain_name, record) - Create a new DNS record
• update_record(domain_name, record_id, record) - Update a DNS record
• delete_record(domain_name, record_id) - Delete a DNS record

Environments

• Production: https://api.name.com
• Sandbox: https://api.dev.name.com

HeroScript Actions

The client supports the following HeroScript actions:

Configure Client

!!namecomclient.configure
    url: 'https://api.name.com'
    username: 'your-username'
    token: 'your-api-token'

List Domains

!!namecomclient.domains_list

List DNS Records

!!namecomclient.records_list
    domain: 'example.com'

Set DNS Record (Create or Update)

!!namecomclient.record_set
    domain: 'example.com'
    host: 'www'
    type: 'A'
    answer: '10.0.0.1'
    ttl: 300
    priority: 0

Use keywords thismachine, thisvm, device, machine, or current to auto-detect the current machine's IP:

!!namecomclient.record_set
    domain: 'example.com'
    host: 'myserver'
    type: 'A'
    answer: 'thismachine'

Delete DNS Record

!!namecomclient.record_delete
    domain: 'example.com'
    host: 'www'
    type: 'A'

Check Domain Availability

!!namecomclient.check_availability
    domains: 'example.org, example.net'

Tips

• Get your API token from your Name.com account settings
• Use the sandbox environment for testing
• API rate limits: 20 requests/second, 3,000 requests/hour
• See the API docs: https://www.name.com/api-docs
• See examples at: examples/clients/namecom/

fn delete(args ArgsGet) !

fn exists(args ArgsGet) !bool

does the config exists?

fn get(args ArgsGet) !&NamecomClient

fn heroscript_loads(heroscript string) !NamecomClient

///////////NORMALLY NO NEED TO TOUCH

fn list(args ArgsList) ![]&NamecomClient

if fromdb set: load from filesystem, and not from mem, will also reset what is in mem

fn new(args ArgsGet) !&NamecomClient

fn play(mut plbook PlayBook) !

fn set(o NamecomClient) !

register the config for the future

fn switch(name string)

switch instance to be used for namecomclient

struct APIError {
pub:
	message string
	details string
}

APIError represents an error response from the API

struct ArgsGet {
pub mut:
	name   string = 'default'
	fromdb bool // will load from filesystem
	create bool // default will not create if not exist
}

///////FACTORY

struct ArgsList {
pub mut:
	fromdb bool // will load from filesystem
}

struct Contact {
pub:
	first_name   string @[json: 'firstName']
	last_name    string @[json: 'lastName']
	company_name string @[json: 'companyName']
	address1     string
	address2     string
	city         string
	state        string
	zip          string
	country      string
	phone        string
	fax          string
	email        string
}

Contact represents contact information

struct Contacts {
pub:
	registrant ?Contact
	admin      ?Contact
	tech       ?Contact
	billing    ?Contact
}

Contacts contains all contact types for a domain

struct CreateRecordRequest {
pub:
	host        string
	record_type string @[json: 'type']
	answer      string
	ttl         u32
	priority    u32
}

CreateRecordRequest is the request body for creating a DNS record

struct DNSRecord {
pub:
	id          int
	domain_name string @[json: 'domainName']
	host        string
	fqdn        string
	record_type string @[json: 'type']
	answer      string
	ttl         u32
	priority    u32
}

DNSRecord represents a DNS record

struct Domain {
pub:
	domain_name       string @[json: 'domainName']
	nameservers       []string
	contacts          ?Contacts
	privacy_enabled   bool @[json: 'privacyEnabled']
	locked            bool
	autorenew_enabled bool   @[json: 'autorenewEnabled']
	expire_date       string @[json: 'expireDate']
	create_date       string @[json: 'createDate']
	renewal_price     f64    @[json: 'renewalPrice']
}

Domain represents a domain in the Name.com account

struct DomainListResponse {
pub:
	domains      []Domain
	current_page int @[json: 'currentPage']
	next_page    int @[json: 'nextPage']
	last_page    int @[json: 'lastPage']
	total_count  int @[json: 'totalCount']
}

DomainListResponse is the response from ListDomains

struct HelloResponse {
pub:
	server_name string @[json: 'serverName']
	motd        string
	username    string
}

HelloResponse is the response from the hello endpoint

struct NamecomClient {
pub mut:
	name     string = 'default'
	username string
	token    string
	url      string = 'https://api.name.com'
}

fn (mut client NamecomClient) check_availability(domain_names []string) ![]SearchResult

check_availability checks if domains are available for purchase

fn (mut client NamecomClient) create_record(domain_name string, record CreateRecordRequest) !DNSRecord

create_record creates a new DNS record

fn (mut client NamecomClient) delete_record(domain_name string, record_id int) !

delete_record deletes a DNS record

fn (mut client NamecomClient) disable_autorenew(domain_name string) !Domain

disable_autorenew disables auto-renewal for a domain

fn (mut client NamecomClient) disable_whois_privacy(domain_name string) !Domain

disable_whois_privacy disables WHOIS privacy for a domain

fn (mut client NamecomClient) enable_autorenew(domain_name string) !Domain

enable_autorenew enables auto-renewal for a domain

fn (mut client NamecomClient) enable_whois_privacy(domain_name string) !Domain

enable_whois_privacy enables WHOIS privacy for a domain

fn (mut client NamecomClient) get_domain(domain_name string) !Domain

get_domain returns details about a specific domain

fn (mut client NamecomClient) get_record(domain_name string, record_id int) !DNSRecord

get_record returns a specific DNS record

fn (mut client NamecomClient) hello() !HelloResponse

hello tests the API connection and returns server info

fn (mut client NamecomClient) list_domains() ![]Domain

list_domains returns all domains in the account

fn (mut client NamecomClient) list_records(domain_name string) ![]DNSRecord

list_records returns all DNS records for a domain

fn (mut client NamecomClient) lock_domain(domain_name string) !Domain

lock_domain locks a domain to prevent transfers

fn (mut client NamecomClient) search(keyword string) ![]SearchResult

search searches for available domains by keyword

fn (mut client NamecomClient) set_contacts(domain_name string, contacts Contacts) !Domain

set_contacts sets the contacts for a domain

fn (mut client NamecomClient) set_nameservers(domain_name string, nameservers []string) !Domain

set_nameservers sets the nameservers for a domain

fn (mut client NamecomClient) unlock_domain(domain_name string) !Domain

unlock_domain unlocks a domain to allow transfers

fn (mut client NamecomClient) update_record(domain_name string, record_id int, record UpdateRecordRequest) !DNSRecord

update_record updates an existing DNS record

struct RecordListResponse {
pub:
	records   []DNSRecord
	next_page int @[json: 'nextPage']
	last_page int @[json: 'lastPage']
}

RecordListResponse is the response from ListRecords

struct SearchResponse {
pub:
	results []SearchResult
}

SearchResponse is the response from Search or CheckAvailability

struct SearchResult {
pub:
	domain_name    string @[json: 'domainName']
	sld            string
	tld            string
	purchasable    bool
	premium        bool
	purchase_price f64    @[json: 'purchasePrice']
	purchase_type  string @[json: 'purchaseType']
	renewal_price  f64    @[json: 'renewalPrice']
}

SearchResult represents a domain search result

struct SetContactsRequest {
pub:
	contacts Contacts
}

SetContactsRequest is the request body for setting contacts

struct SetNameserversRequest {
pub:
	nameservers []string
}

SetNameserversRequest is the request body for setting nameservers

struct UpdateRecordRequest {
pub:
	host        string
	record_type string @[json: 'type']
	answer      string
	ttl         u32
	priority    u32
}

UpdateRecordRequest is the request body for updating a DNS record