porkbun

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2024 License: MIT Imports: 10 Imported by: 0

README

Porkbun Go SDK

Go Report Card GoDoc

The Porkbun Go SDK is a fully-featured Go client for interacting with the Porkbun API v3. This SDK simplifies integration with Porkbun's services, providing an easy-to-use and comprehensive interface for managing domains, DNS records, SSL certificates, and more.

Features

  • Domain management: List, create, update, and delete domains.
  • DNS management: Full control over DNS records including creation, retrieval, updating, and deletion.
  • SSL management: Retrieve SSL certificate bundles for domains.
  • URL forwarding: Manage domain URL forwarding settings.
  • Built-in error handling and support for custom data types (e.g., BoolString, BoolNumber).

Installation

Install the SDK using go get:

go get github.com/tuzzmaniandevil/porkbun-go

Usage

Basic Usage

Below is a quick example demonstrating how to use the SDK to list all domains in your Porkbun account:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/tuzzmaniandevil/porkbun-go"
)

func main() {
    client := porkbun.NewClient(&porkbun.Options{
        ApiKey:       "your_api_key",
        SecretApiKey: "your_secret_api_key",
    })

    resp, err := client.Domains.ListDomains(context.Background(), &porkbun.DomainListOptions{})
    if err != nil {
        log.Fatalf("Error listing domains: %v", err)
    }

    for _, domain := range resp.Domains {
        fmt.Println(domain.Domain)
    }
}
Advanced Usage

For advanced usage, including custom API requests and handling more complex scenarios, refer to the examples directory in the repository.

Documentation

Comprehensive documentation is available on GoDoc.

Testing

Run the tests using go test:

go test ./...

Ensure you have your API credentials set up in the environment or replace them directly in the test files for local testing.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.

Guidelines
  • Write clear, concise commit messages.
  • Ensure all tests pass before submitting a pull request.
  • Follow the existing code style and format your code with gofmt.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

  • Porkbun for providing a robust API.
  • Go community for tools and inspiration.

Documentation

Index

Constants

View Source 
const (
	Version = "1.0.0"
)

Variables

This section is empty.

Functions

func String 

func String(v string) *string

String is a helper function that allocates a new string value and returns a pointer to it.

Types

type AddDomainUrlForwardRequest 

type AddDomainUrlForwardRequest struct {
	BaseRequest
	*UrlForward // Embeds the UrlForward to include the forward details
}

AddDomainUrlForwardRequest represents the request structure for adding a new URL forward.

type AddDomainUrlForwardResponse 

type AddDomainUrlForwardResponse struct {
	BaseResponse
}

AddDomainUrlForwardResponse represents the response structure for adding a new URL forward.

type ApiKeyAcceptor 

type ApiKeyAcceptor interface {
	SetCredentials(apiKey string, secretApiKey string)
}

ApiKeyAcceptor defines an interface for setting API credentials.

type BaseRequest 

type BaseRequest struct {
	SecretApiKey string `json:"secretapikey"` // The secret API key provided by Porkbun.
	Apikey       string `json:"apikey"`       // The public API key provided by Porkbun.
}

BaseRequest represents the base structure for all API requests, including credentials.

func (*BaseRequest) SetCredentials 

func (br *BaseRequest) SetCredentials(apiKey string, secretApiKey string)

SetCredentials sets the API and secret keys for the request.

type BaseResponse 

type BaseResponse struct {
	HTTPResponse *http.Response // The underlying HTTP Response.
	Status       string         `json:"status"` // Status indicating whether the command was successfully processed.
}

BaseResponse represents the base structure for all API responses.

type BoolNumber 

type BoolNumber bool

BoolNumber is a custom type for handling boolean values represented as 1/0 numbers in JSON.

func (*BoolNumber) UnmarshalJSON 

func (b *BoolNumber) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshalling logic for BoolNumber.

type BoolString 

type BoolString bool

BoolString is a custom type for handling boolean values represented as "1"/"0" strings in JSON.

func (*BoolString) UnmarshalJSON 

func (b *BoolString) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshalling logic for BoolString.

type Client 

type Client struct {

	// Services
	Pricing *PricingService
	Domains *DomainsService
	Dns     *DnsService
	Ssl     *SslService
	// contains filtered or unexported fields
}

Client represents a Porkbun API client.

func NewClient 

func NewClient(options *Options) *Client

NewClient initializes a new Porkbun API client with the provided options.

func (*Client) Ping 

func (s *Client) Ping(ctx context.Context) (*PingResponse, error)

Ping pings the Porkbun API to check its availability and returns the client's IP address.

type Coupon 

type Coupon struct {
	Code          string `json:"code"`            // Coupon code
	MaxPerUser    int64  `json:"max_per_user"`    // Maximum number of uses per user
	FirstYearOnly string `json:"first_year_only"` // Indicates if the coupon is applicable only for the first year
	Type          string `json:"type"`            // Type of discount (e.g., amount, percentage)
	Amount        int64  `json:"amount"`          // Discount amount
}

Coupon represents the details of a coupon, such as the code, limits, applicability, and discount amount.

type Coupons 

type Coupons map[string]Coupon

Coupons is a custom type that represents either a map of coupon codes to Coupon details or an empty array, which is unmarshaled as a nil map.

func (*Coupons) UnmarshalJSON 

func (c *Coupons) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the unmarshaling of the Coupons field, which can be either a map of coupons or an empty array. This method ensures correct parsing based on the input type.

type CreateRecordRequest 

type CreateRecordRequest struct {
	BaseRequest
	*DnsRecord // Embeds the DnsRecord to include DNS record details
}

CreateRecordRequest represents the request structure for creating a DNS record.

type CreateRecordResponse 

type CreateRecordResponse struct {
	BaseResponse
	ID int64 `json:"id"` // ID of the newly created DNS record
}

CreateRecordResponse represents the response structure for creating a DNS record.

type DeleteDomainUrlForwardRequest 

type DeleteDomainUrlForwardRequest struct {
	BaseRequest
}

DeleteDomainUrlForwardRequest represents the request structure for deleting a URL forward.

type DeleteDomainUrlForwardResponse 

type DeleteDomainUrlForwardResponse struct {
	BaseResponse
}

DeleteDomainUrlForwardResponse represents the response structure for deleting a URL forward.

type DeleteRecordRequest 

type DeleteRecordRequest struct {
	BaseRequest
}

DeleteRecordRequest represents the request structure for deleting a DNS record.

type DeleteRecordResponse 

type DeleteRecordResponse struct {
	BaseResponse
}

DeleteRecordResponse represents the response structure for deleting a DNS record.

type DnsRecord 

type DnsRecord struct {
	ID      *int64        `json:"id,omitempty"`    // DNS record ID (optional for new records)
	Name    string        `json:"name"`            // Subdomain name for the DNS record
	Type    DnsRecordType `json:"type"`            // DNS record type
	Content string        `json:"content"`         // DNS record content
	TTL     string        `json:"ttl,omitempty"`   // Time to live (TTL) for the DNS record
	Prio    string        `json:"prio,omitempty"`  // Priority for the DNS record (if applicable)
	Notes   string        `json:"notes,omitempty"` // Additional notes (optional)
}

DnsRecord represents a DNS record in the system.

func (*DnsRecord) UnmarshalJSON 

func (d *DnsRecord) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the custom unmarshalling of the DnsRecord struct.

type DnsRecordType 

type DnsRecordType string

DnsRecordType represents a DNS record type as a string enum. 

const (
	A     DnsRecordType = "A"
	MX    DnsRecordType = "MX"
	CNAME DnsRecordType = "CNAME"
	ALIAS DnsRecordType = "ALIAS"
	TXT   DnsRecordType = "TXT"
	NS    DnsRecordType = "NS"
	AAAA  DnsRecordType = "AAAA"
	SRV   DnsRecordType = "SRV"
	TLSA  DnsRecordType = "TLSA"
	CAA   DnsRecordType = "CAA"
	HTTPS DnsRecordType = "HTTPS"
	SVCB  DnsRecordType = "SVCB"
)

Enum values for DnsRecordType

func (DnsRecordType) IsValid 

func (rt DnsRecordType) IsValid() bool

IsValid checks if the DnsRecordType is valid.

func (DnsRecordType) String 

func (rt DnsRecordType) String() string

String returns the string representation of the DnsRecordType.

func (DnsRecordType) ToPtr 

func (rt DnsRecordType) ToPtr() *string

ToPtr returns a pointer to the string representation of the DnsRecordType.

type DnsService 

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

DnsService provides methods to interact with the DNS record management API.

func (*DnsService) CreateRecord 

func (s *DnsService) CreateRecord(ctx context.Context, domain string, record *DnsRecord) (*CreateRecordResponse, error)

CreateRecord creates a new DNS record for a domain.

func (*DnsService) DeleteRecord 

func (s *DnsService) DeleteRecord(ctx context.Context, domain string, recordId int64) (*DeleteRecordResponse, error)

DeleteRecord deletes a specific DNS record for a domain by record ID.

func (*DnsService) DeleteRecordByType 

func (s *DnsService) DeleteRecordByType(ctx context.Context, domain string, recordType DnsRecordType, subdomain *string) (*DeleteRecordResponse, error)

DeleteRecordByType deletes all DNS records for a domain that match a particular type and (optional) subdomain.

func (*DnsService) EditRecord 

func (s *DnsService) EditRecord(ctx context.Context, domain string, recordId int64, record *EditRecord) (*EditRecordResponse, error)

EditRecord edits an existing DNS record for a domain by record ID.

func (*DnsService) EditRecordByType 

func (s *DnsService) EditRecordByType(ctx context.Context, domain string, recordType DnsRecordType, subdomain *string, record *EditTypeRecord) (*EditRecordResponse, error)

EditRecordByType edits all DNS records for a domain that match a particular type and subdomain.

func (*DnsService) GetRecords 

func (s *DnsService) GetRecords(ctx context.Context, domain string, recordId *int64) (*GetRecordsResponse, error)

GetRecords retrieves DNS records for a domain, optionally filtered by record ID.

func (*DnsService) GetRecordsByType 

func (s *DnsService) GetRecordsByType(ctx context.Context, domain string, recordType DnsRecordType, subdomain *string) (*GetRecordsResponse, error)

GetRecordsByType retrieves DNS records for a domain by record type and subdomain.

type Domain 

type Domain struct {
	Domain       string     `json:"domain"`           // The domain name
	Status       string     `json:"status"`           // The status of the domain (e.g., ACTIVE)
	TLD          string     `json:"tld"`              // The top-level domain (TLD)
	CreateDate   time.Time  `json:"createDate"`       // The date the domain was created
	ExpireDate   time.Time  `json:"expireDate"`       // The date the domain will expire
	SecurityLock BoolString `json:"securityLock"`     // Indicates if the domain has a security lock (true/false)
	WhoisPrivacy BoolString `json:"whoisPrivacy"`     // Indicates if WHOIS privacy is enabled (true/false)
	AutoRenew    BoolNumber `json:"autoRenew"`        // Indicates if auto-renewal is enabled (true/false)
	NotLocal     BoolNumber `json:"notLocal"`         // Indicates if the domain is not local (true/false)
	Labels       []Label    `json:"labels,omitempty"` // Optional labels associated with the domain
}

Domain represents the details of a domain, including its status, creation/expiration dates, and various settings.

func (*Domain) UnmarshalJSON 

func (d *Domain) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the custom unmarshalling of the Domain struct, including parsing dates.

type DomainListOptions 

type DomainListOptions struct {
	Start         *string // Optional start index for pagination
	IncludeLabels *string // Optional flag to include label information
}

DomainListOptions provides options for filtering the list of domains.

type DomainsService 

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

DomainsService provides methods to interact with the domain management API.

func (*DomainsService) AddDomainUrlForward 

func (s *DomainsService) AddDomainUrlForward(ctx context.Context, domain string, forwardAttributes *UrlForward) (*AddDomainUrlForwardResponse, error)

AddDomainUrlForward adds a new URL forward for the specified domain.

func (*DomainsService) DeleteDomainUrlForward 

func (s *DomainsService) DeleteDomainUrlForward(ctx context.Context, domain string, recordId string) (*DeleteDomainUrlForwardResponse, error)

DeleteDomainUrlForward deletes a URL forward for the specified domain by record ID.

func (*DomainsService) GetDomainURLForwarding 

func (s *DomainsService) GetDomainURLForwarding(ctx context.Context, domain string) (*GetDomainURLForwardingResponse, error)

GetDomainURLForwarding retrieves the list of URL forwards for a specified domain.

func (*DomainsService) GetNameServers 

func (s *DomainsService) GetNameServers(ctx context.Context, domain string) (*GetNameServersResponse, error)

GetNameServers retrieves the current name servers for the specified domain.

func (*DomainsService) ListDomains 

func (s *DomainsService) ListDomains(ctx context.Context, options *DomainListOptions) (*ListDomainsResponse, error)

ListDomains retrieves a list of domains associated with the account, with optional filters for pagination and labels.

func (*DomainsService) UpdateNameServers 

func (s *DomainsService) UpdateNameServers(ctx context.Context, domain string, newNameservers *NameServers) (*UpdateNameServersResponse, error)

UpdateNameServers updates the name servers for the specified domain.

type EditRecord 

type EditRecord struct {
	Name    string        `json:"name"`           // Subdomain name for the DNS record
	Type    DnsRecordType `json:"type"`           // DNS record type
	Content string        `json:"content"`        // DNS record content
	TTL     string        `json:"ttl,omitempty"`  // Time to live (TTL) for the DNS record
	Prio    string        `json:"prio,omitempty"` // Priority for the DNS record (if applicable)
}

EditRecord represents the details required to edit a DNS record.

type EditRecordRequest 

type EditRecordRequest struct {
	BaseRequest
	*EditRecord // Embeds the EditRecord to include DNS record details to be edited
}

EditRecordRequest represents the request structure for editing a DNS record.

type EditRecordResponse 

type EditRecordResponse struct {
	BaseResponse
}

EditRecordResponse represents the response structure for editing a DNS record.

type EditRecordTypeRequest 

type EditRecordTypeRequest struct {
	BaseRequest
	*EditTypeRecord // Embeds the EditTypeRecord to include DNS record details to be edited
}

EditRecordTypeRequest represents the request structure for editing DNS records by type.

type EditTypeRecord 

type EditTypeRecord struct {
	Content string `json:"content"`        // DNS record content
	TTL     string `json:"ttl,omitempty"`  // Time to live (TTL) for the DNS record
	Prio    string `json:"prio,omitempty"` // Priority for the DNS record (if applicable)
}

EditTypeRecord represents the details required to edit DNS records by type.

type ErrorResponse 

type ErrorResponse struct {
	BaseResponse
	Message string `json:"message,omitempty"` // The error message provided by the API.
}

ErrorResponse represents an error response from the API.

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

Error implements the error interface for ErrorResponse.

type ForwardType 

type ForwardType string

ForwardType is a custom type for specifying the type of URL forward. 

const (
	Temporary ForwardType = "temporary"
	Permanent ForwardType = "permanent"
)

Constants representing valid values for ForwardType.

type GetDomainURLForwardingRequest 

type GetDomainURLForwardingRequest struct {
	BaseRequest // Embeds the BaseRequest to include API credentials
}

GetDomainURLForwardingRequest represents the request structure for retrieving domain URL forwards.

type GetDomainURLForwardingResponse 

type GetDomainURLForwardingResponse struct {
	BaseResponse
	Forwards []UrlForwardData `json:"forwards"` // List of URL forwards for the domain
}

GetDomainURLForwardingResponse represents the response structure for retrieving domain URL forwards.

type GetNameServersRequest 

type GetNameServersRequest struct {
	BaseRequest // Embeds the BaseRequest to include API credentials
}

GetNameServersRequest represents the request structure for retrieving name servers.

type GetNameServersResponse 

type GetNameServersResponse struct {
	BaseResponse
	NS NameServers `json:"ns"` // An array of name server hostnames
}

GetNameServersResponse represents the response structure for retrieving name servers.

type GetRecordsRequest 

type GetRecordsRequest struct {
	BaseRequest // Embeds the BaseRequest to include API credentials
}

GetRecordsRequest represents the request structure for retrieving DNS records.

type GetRecordsResponse 

type GetRecordsResponse struct {
	BaseResponse
	Records []DnsRecord `json:"records"` // List of DNS records
}

GetRecordsResponse represents the response structure for retrieving DNS records.

type HTTPClient 

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient defines an interface for making HTTP requests.

type Label 

type Label struct {
	ID    string `json:"id"`    // The ID of the label
	Title string `json:"title"` // The title of the label
	Color string `json:"color"` // The color associated with the label
}

Label represents a label that can be associated with a domain, including its ID, title, and color.

type ListDomainsRequest 

type ListDomainsRequest struct {
	BaseRequest
	Start         *string `json:"start,omitempty"`         // Optional start index for pagination
	IncludeLabels *string `json:"includeLabels,omitempty"` // Optional flag to include label information
}

ListDomainsRequest represents the request structure for listing domains.

type ListDomainsResponse 

type ListDomainsResponse struct {
	BaseResponse
	Domains []Domain `json:"domains"` // Array of domains and their details
}

ListDomainsResponse represents the response structure for listing domains.

type NameServers 

type NameServers []string

NameServers represents an array of name server hostnames.

type Options 

type Options struct {
	HttpClient   *HTTPClient // Custom HTTP client, defaults to http.Client if nil.
	ApiKey       string      // Public API key provided by Porkbun.
	SecretApiKey string      // Secret API key provided by Porkbun.
	IPv4Only     bool        // If true, use IPv4-only base URL.
	UserAgent    string      // Custom User-Agent string, defaults to "porkbun-go/1.0.0".
}

Options defines the configuration options for the Porkbun API client.

type PingRequest 

type PingRequest struct {
	BaseRequest
}

PingRequest represents the request structure for the Ping API.

type PingResponse 

type PingResponse struct {
	BaseResponse
	YourIP string `json:"yourIp"` // The IP address of the client making the request.
}

PingResponse represents the response structure for the Ping API.

type Pricing 

type Pricing struct {
	Registration string  `json:"registration"`          // Cost of domain registration
	Renewal      string  `json:"renewal"`               // Cost of domain renewal
	Transfer     string  `json:"transfer"`              // Cost of domain transfer
	Coupons      Coupons `json:"coupons,omitempty"`     // Applicable coupons, if any
	SpecialType  *string `json:"specialType,omitempty"` // Optional special pricing type
}

Pricing represents the pricing information for a domain, including registration, renewal, transfer costs, and any applicable coupons.

type PricingResponse 

type PricingResponse struct {
	BaseResponse
	Pricing map[string]Pricing `json:"pricing"` // Map of domain type to pricing details
}

PricingResponse wraps the response from the pricing API, including the base response and the pricing details for various domain types.

type PricingService 

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

PricingService provides methods to interact with the pricing API.

func (*PricingService) ListPricing 

func (s *PricingService) ListPricing(ctx context.Context) (*PricingResponse, error)

ListPricing retrieves the pricing information for various domain types from the API. It returns a PricingResponse containing the parsed pricing data.

type SslRetrieveRequest 

type SslRetrieveRequest struct {
	BaseRequest // Embeds the BaseRequest to include API credentials
}

SslRetrieveRequest represents the request structure for retrieving an SSL certificate.

type SslRetrieveResponse 

type SslRetrieveResponse struct {
	BaseResponse

	Certificatechain string `json:"certificatechain"` // The complete certificate chain
	Privatekey       string `json:"privatekey"`       // The private key
	Publickey        string `json:"publickey"`        // The public key
}

SslRetrieveResponse represents the response structure for an SSL certificate retrieval, including the certificate chain, private key, and public key.

type SslService 

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

SslService provides methods to interact with the SSL certificate management API.

func (*SslService) Retrieve 

func (s *SslService) Retrieve(ctx context.Context, domain string) (*SslRetrieveResponse, error)

Retrieve fetches the SSL certificate bundle for the specified domain.

type UpdateNameServersRequest 

type UpdateNameServersRequest struct {
	BaseRequest
	NS NameServers `json:"ns"` // An array of name servers to update the domain with
}

UpdateNameServersRequest represents the request structure for updating name servers.

type UpdateNameServersResponse 

type UpdateNameServersResponse struct {
	BaseResponse
}

UpdateNameServersResponse represents the response structure for updating name servers.

type UrlForward 

type UrlForward struct {
	Subdomain   string      `json:"subdomain"`   // Optional subdomain to forward, empty if forwarding the root domain
	Location    string      `json:"location"`    // The destination URL for the forward
	Type        ForwardType `json:"type"`        // The type of forward: "temporary" or "permanent"
	IncludePath string      `json:"includePath"` // Whether to include the URI path in the forward: "yes" or "no"
	Wildcard    string      `json:"wildcard"`    // Whether to forward all subdomains: "yes" or "no"`
}

UrlForward represents the details of a URL forward for a domain.

type UrlForwardData 

type UrlForwardData struct {
	Id string `json:"id"` // The ID of the URL forward
	UrlForward
}

UrlForwardData represents the data structure for a URL forward, including its ID.

Source Files

View all Source files

Directories

Path Synopsis

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.