namecom

package
v1.801.459 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 5, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package namecom is a minimal client for the name.com Core API v4 — the wholesale registrar surface Hanzo Domains resells: check availability, price, register, renew, transfer, and set nameservers/contacts on a domain.

Contract (name.com Core API v4):

  • Base URL: https://api.name.com (production), https://api.dev.name.com (test).
  • Auth: HTTP Basic — username + API token.
  • Actions use a ":verb" suffix on the collection/resource, e.g. POST /v4/domains:checkAvailability, POST /v4/domains/{domain}:setNameservers.

Credentials are NEVER hard-coded here: the caller passes the username/token it read from the platform secret store (KMS), exactly as the Cloudflare purger reads CF_API_TOKEN. This package holds no secret custody of its own.

Index

Constants

View Source 
const (
	BaseProd = "https://api.name.com"
	BaseTest = "https://api.dev.name.com"
)

Base URLs for the two name.com environments. Test is a full sandbox connected to the registries' own test systems — register/renew/transfer are exercisable there with no real charge.

Variables

This section is empty.

Functions

func BaseFor 

func BaseFor(env string) string

BaseFor maps an environment slug to its base URL. Anything other than "prod"/ "production"/"mainnet" resolves to the TEST sandbox — fail-safe: an unset or misspelled env can never accidentally hit the live, billable registrar.

Types

type APIError 

type APIError struct {
	Status  int    `json:"-"`
	Message string `json:"message"`
	Details string `json:"details"`
}

APIError is a non-2xx response from name.com. name.com returns {"message":"...","details":"..."} on error; both are surfaced.

func (*APIError) Error 

func (e *APIError) Error() string

type AvailabilityRequest 

type AvailabilityRequest struct {
	DomainNames []string `json:"domainNames"`
}

AvailabilityRequest is the body of POST /v4/domains:checkAvailability.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client calls the name.com v4 API with HTTP Basic auth. It is safe to share across goroutines. A zero token/user yields a client whose calls fail closed at name.com (401/403) rather than panicking — the caller checks Configured() to degrade early.

func New 

func New(user, token, env string, httpClient *http.Client) *Client

New builds a client for (user, token) against the base URL for env. httpClient is optional (nil ⇒ a 20s-timeout default).

func NewWithBase 

func NewWithBase(user, token, base string, httpClient *http.Client) *Client

NewWithBase is New with an explicit base URL — used by tests to point at an httptest server.

func (*Client) CheckAvailability 

func (c *Client) CheckAvailability(ctx context.Context, names ...string) (*SearchResponse, error)

CheckAvailability checks one or more exact domain names: POST /v4/domains:checkAvailability. Each result carries purchasable + the wholesale first-term and renewal prices (USD).

func (*Client) Configured 

func (c *Client) Configured() bool

Configured reports whether both a username and a token are present, i.e. whether a call has any chance of authenticating.

func (*Client) CreateDomain 

func (c *Client) CreateDomain(ctx context.Context, req CreateDomainRequest) (*CreateDomainResponse, error)

CreateDomain registers a domain: POST /v4/domains. This DEBITS the reseller account at name.com by the wholesale price. purchasePrice caps the accepted charge (a price change above it is rejected). years defaults to 1.

func (*Client) CreateTransfer 

func (c *Client) CreateTransfer(ctx context.Context, req TransferRequest) (*TransferResponse, error)

CreateTransfer starts a transfer-in of a domain the customer owns elsewhere: POST /v4/transfers. authCode is the EPP/auth code from the losing registrar.

func (*Client) GetDomain 

func (c *Client) GetDomain(ctx context.Context, domain string) (*Domain, error)

GetDomain reads one domain the reseller owns: GET /v4/domains/{domain}.

func (*Client) Hello 

func (c *Client) Hello(ctx context.Context) (*HelloResponse, error)

Hello probes auth + connectivity: GET /v4/hello. A 2xx means the credentials are accepted and API access is enabled for the account; a 403 "Permission Denied" means the token is IP-locked or the account lacks API/reseller access.

func (*Client) ListDomains 

func (c *Client) ListDomains(ctx context.Context) (*ListDomainsResponse, error)

ListDomains lists the domains the reseller owns: GET /v4/domains.

func (*Client) RenewDomain 

func (c *Client) RenewDomain(ctx context.Context, domain string, req RenewDomainRequest) (*RenewDomainResponse, error)

RenewDomain renews a registered domain: POST /v4/domains/{domain}:renew.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, keyword string, tldFilter ...string) (*SearchResponse, error)

Search runs a keyword search that also suggests alternate TLDs: POST /v4/domains:search. tldFilter (optional) narrows the returned TLDs.

func (*Client) SetContacts 

func (c *Client) SetContacts(ctx context.Context, domain string, contacts Contacts) (*Domain, error)

SetContacts updates the WHOIS contact set: POST /v4/domains/{domain}:setContacts.

func (*Client) SetNameservers 

func (c *Client) SetNameservers(ctx context.Context, domain string, nameservers []string) (*Domain, error)

SetNameservers points a registered domain at the given authoritative nameservers: POST /v4/domains/{domain}:setNameservers. This is the step that hands DNS control to Hanzo's own nameservers after registration.

type Contact 

type Contact struct {
	FirstName string `json:"firstName,omitempty"`
	LastName  string `json:"lastName,omitempty"`
	Company   string `json:"companyName,omitempty"`
	Address1  string `json:"address1,omitempty"`
	Address2  string `json:"address2,omitempty"`
	City      string `json:"city,omitempty"`
	State     string `json:"state,omitempty"`
	Zip       string `json:"zip,omitempty"`
	Country   string `json:"country,omitempty"` // ISO-3166 alpha-2, e.g. "US"
	Phone     string `json:"phone,omitempty"`   // +NN.NNNNNNN
	Fax       string `json:"fax,omitempty"`
	Email     string `json:"email,omitempty"`
}

Contact is a WHOIS/registration contact. name.com requires registrant/admin/tech/ billing contacts on register; missing ones default to the reseller account.

type Contacts 

type Contacts struct {
	Registrant *Contact `json:"registrant,omitempty"`
	Admin      *Contact `json:"admin,omitempty"`
	Tech       *Contact `json:"tech,omitempty"`
	Billing    *Contact `json:"billing,omitempty"`
}

Contacts is the four-role contact set for a domain.

type CreateDomainRequest 

type CreateDomainRequest struct {
	Domain          DomainInput       `json:"domain"`
	PurchasePrice   float64           `json:"purchasePrice,omitempty"`
	Years           int               `json:"years,omitempty"`
	TLDRequirements map[string]string `json:"tldRequirements,omitempty"`
}

CreateDomainRequest is the body of POST /v4/domains (register). purchasePrice is the price the caller EXPECTS to pay (the wholesale quote from availability); name.com rejects a registration whose real price exceeds it — a guard against a price change between quote and buy. years defaults to 1.

type CreateDomainResponse 

type CreateDomainResponse struct {
	Domain    *Domain `json:"domain"`
	Order     int64   `json:"order,omitempty"`
	TotalPaid float64 `json:"totalPaid,omitempty"`
}

CreateDomainResponse is the register result: the created domain plus what name.com actually charged the reseller account (order + totalPaid, USD).

type Domain 

type Domain struct {
	DomainName   string    `json:"domainName"`
	Nameservers  []string  `json:"nameservers,omitempty"`
	Contacts     *Contacts `json:"contacts,omitempty"`
	Locked       bool      `json:"locked,omitempty"`
	AutorenewOn  bool      `json:"autorenewEnabled,omitempty"`
	ExpireDate   string    `json:"expireDate,omitempty"`   // RFC3339
	CreateDate   string    `json:"createDate,omitempty"`   // RFC3339
	RenewalPrice float64   `json:"renewalPrice,omitempty"` // USD
	PrivacyOn    bool      `json:"privacyEnabled,omitempty"`
}

Domain is a domain record as name.com returns it (get/create/renew/setNameservers).

type DomainInput 

type DomainInput struct {
	DomainName  string    `json:"domainName"`
	Nameservers []string  `json:"nameservers,omitempty"`
	Contacts    *Contacts `json:"contacts,omitempty"`
	PrivacyOn   bool      `json:"privacyEnabled,omitempty"`
}

DomainInput is the domain sub-object of a create request.

type HelloResponse 

type HelloResponse struct {
	ServerName string `json:"serverName,omitempty"`
	Motd       string `json:"motd,omitempty"`
	Username   string `json:"username,omitempty"`
}

HelloResponse is the body of GET /v4/hello — the auth/health probe.

type ListDomainsResponse 

type ListDomainsResponse struct {
	Domains  []Domain `json:"domains"`
	NextPage int      `json:"nextPage,omitempty"`
}

ListDomainsResponse is the body of GET /v4/domains.

type RenewDomainRequest 

type RenewDomainRequest struct {
	PurchasePrice float64 `json:"purchasePrice,omitempty"`
	Years         int     `json:"years,omitempty"`
}

RenewDomainRequest is the body of POST /v4/domains/{domain}:renew.

type RenewDomainResponse 

type RenewDomainResponse struct {
	Domain    *Domain `json:"domain"`
	Order     int64   `json:"order,omitempty"`
	TotalPaid float64 `json:"totalPaid,omitempty"`
}

RenewDomainResponse is the renew result.

type SearchRequest 

type SearchRequest struct {
	Keyword   string   `json:"keyword"`
	TLDFilter []string `json:"tldFilter,omitempty"`
	Timeout   int      `json:"timeout,omitempty"` // ms; name.com caps the search
}

SearchRequest is the body of POST /v4/domains:search — a keyword search that also suggests alternate TLDs. tldFilter narrows to specific TLDs (e.g. ["ai","com"]).

type SearchResponse 

type SearchResponse struct {
	Results []SearchResult `json:"results"`
}

SearchResponse wraps the results for both search and checkAvailability.

type SearchResult 

type SearchResult struct {
	DomainName    string  `json:"domainName"`
	SLD           string  `json:"sld,omitempty"`
	TLD           string  `json:"tld,omitempty"`
	Purchasable   bool    `json:"purchasable"`
	Premium       bool    `json:"premium,omitempty"`
	PurchasePrice float64 `json:"purchasePrice,omitempty"` // first-term registration, USD
	PurchaseType  string  `json:"purchaseType,omitempty"`  // "registration" | "renewal" | ...
	RenewalPrice  float64 `json:"renewalPrice,omitempty"`  // USD
	Transferable  bool    `json:"transferable,omitempty"`
}

SearchResult is one candidate in a search / availability response. Prices are USD.

type SetContactsRequest 

type SetContactsRequest struct {
	Contacts Contacts `json:"contacts"`
}

SetContactsRequest is the body of POST /v4/domains/{domain}:setContacts.

type SetNameserversRequest 

type SetNameserversRequest struct {
	Nameservers []string `json:"nameservers"`
}

SetNameserversRequest is the body of POST /v4/domains/{domain}:setNameservers — this is how a registered domain is pointed at Hanzo's authoritative nameservers.

type Transfer 

type Transfer struct {
	DomainName string `json:"domainName"`
	Email      string `json:"email,omitempty"`
	Status     string `json:"status,omitempty"`
}

Transfer is a transfer record as name.com returns it.

type TransferRequest 

type TransferRequest struct {
	DomainName    string  `json:"domainName"`
	AuthCode      string  `json:"authCode"`
	PurchasePrice float64 `json:"purchasePrice,omitempty"`
	Years         int     `json:"years,omitempty"`
}

TransferRequest is the body of POST /v4/transfers (transfer a domain IN to Hanzo).

type TransferResponse 

type TransferResponse struct {
	Transfer  *Transfer `json:"transfer"`
	Order     int64     `json:"order,omitempty"`
	TotalPaid float64   `json:"totalPaid,omitempty"`
}

TransferResponse is the create-transfer result.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.