api

Documentation

Overview

Package api implements a minimal HTTP client for the Dymmer hosting API.

Index

• type APIError
  • func (e *APIError) Error() string
• type Client
  • func NewClient(baseURL, token string, httpClient *http.Client) *Client
  • func (c *Client) CreateRecord(ctx context.Context, domain string, input RecordInput) (*Record, error)
  • func (c *Client) DeleteRecord(ctx context.Context, domain, id string) (*Record, error)
  • func (c *Client) GetSecrets(ctx context.Context, project, env, deployment, format string) (*SecretsResult, error)
  • func (c *Client) ListForwardings(ctx context.Context, domain string) ([]Forwarding, error)
  • func (c *Client) ListMailboxes(ctx context.Context, domain string) ([]Mailbox, error)
  • func (c *Client) ListRecords(ctx context.Context, domain, recordType string) ([]Record, error)
  • func (c *Client) UpdateRecord(ctx context.Context, domain, id string, input RecordInput) (*Record, error)
• type Forwarding
• type Mailbox
• type Record
• type RecordInput
• type SecretEntry
• type SecretsResult

Types

type APIError

type APIError struct {
	StatusCode int
	Reason     string
	Errors     map[string][]string
}

APIError represents a non-2xx response from the Dymmer API. Its Error() message never includes request headers or the auth token: it is built exclusively from the response status code and (when parseable) the response body's reason/error fields.

func (*APIError) Error

func (e *APIError) Error() string

type Client

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

Client is a thin HTTP client for the Dymmer API. baseURL must already include any API path prefix (e.g. "https://dymmer.com/api/v1"); Client never adds one of its own, it only appends resource paths.

func NewClient

func NewClient(baseURL, token string, httpClient *http.Client) *Client

NewClient builds a Client that authenticates every request with "Authorization: Bearer <token>".

func (*Client) CreateRecord

func (c *Client) CreateRecord(ctx context.Context, domain string, input RecordInput) (*Record, error)

CreateRecord creates a new record on domain.

func (*Client) DeleteRecord

func (c *Client) DeleteRecord(ctx context.Context, domain, id string) (*Record, error)

DeleteRecord removes the record identified by id on domain and returns the record as it existed just before deletion.

func (*Client) GetSecrets

func (c *Client) GetSecrets(ctx context.Context, project, env, deployment, format string) (*SecretsResult, error)

GetSecrets fetches secrets for project (required), env, and optionally deployment (omitted from the request entirely when empty).

format must be the *wire* value the Dymmer server understands, not a CLI-facing name: pass "" or "json" for JSON output, and the literal string ".env" for dotenv output. The server only recognizes the exact string ".env" to mean dotenv; any other value (including the strings "json" or "dotenv") falls back to JSON. Callers translating a user-facing --format flag (e.g. "dotenv") must map it to ".env" themselves before calling GetSecrets — this package does not do that translation, to keep the CLI/server format-name mismatch visible at the call site instead of hidden here.

func (*Client) ListForwardings

func (c *Client) ListForwardings(ctx context.Context, domain string) ([]Forwarding, error)

ListForwardings fetches the mail forwardings configured for domain.

func (*Client) ListMailboxes

func (c *Client) ListMailboxes(ctx context.Context, domain string) ([]Mailbox, error)

ListMailboxes fetches the mailboxes configured for domain.

func (*Client) ListRecords

func (c *Client) ListRecords(ctx context.Context, domain, recordType string) ([]Record, error)

ListRecords fetches the records for domain, optionally filtered by exact record type match (e.g. "A"). An empty recordType omits the filter.

func (*Client) UpdateRecord

func (c *Client) UpdateRecord(ctx context.Context, domain, id string, input RecordInput) (*Record, error)

UpdateRecord replaces the record identified by id on domain.

type Forwarding

type Forwarding struct {
	Username    string   `json:"username"`
	Destination []string `json:"destination"`
	Enabled     bool     `json:"enabled"`
}

Forwarding is a single mail forwarding rule as returned by the Dymmer API. Destination can fan out to multiple addresses.

type Mailbox

type Mailbox struct {
	Username    string `json:"username"`
	PasswordMD5 string `json:"password_md5"`
	Enabled     bool   `json:"enabled"`
}

Mailbox is a single mailbox as returned by the Dymmer API. PasswordMD5 is an opaque hash, not a plaintext credential.

type Record

type Record struct {
	ID         string            `json:"id"`
	Type       string            `json:"type"`
	Host       string            `json:"host"`
	TimeToLive int               `json:"time_to_live"`
	Content    map[string]string `json:"content"`
}

Record is a single DNS record as returned by the Dymmer API. Content holds the record's type-specific fields (e.g. "ip" for an A record, "value" for a TXT record) as returned by the server, keyed without the "content_" prefix used on the wire for writes.

type RecordInput

type RecordInput struct {
	Type    string
	Host    string
	TTL     *int
	Content map[string]string
}

RecordInput describes the fields a caller wants to set when creating or updating a record. Content keys are the bare field names (e.g. "ip", "value", "priority") — CreateRecord/UpdateRecord serialize each one as a top-level "content_<key>" field on the request body, so this package never needs to know which record types accept which fields; that mapping lives in the CLI command layer.

Host and TTL are optional: an empty Host is omitted from the request (the server defaults it to "@"), and a nil TTL is omitted (the server defaults it to 3600). Type is always sent, even on updates where it is unchanged, since the server uses it to select content validation.

type SecretEntry

type SecretEntry struct {
	Key      string `json:"key"`
	Value    string `json:"value"`
	Comments string `json:"comments"`
	Removed  bool   `json:"removed"`
}

SecretEntry is a single secret as returned by the Dymmer API's JSON secrets format.

type SecretsResult

type SecretsResult struct {
	Raw     string
	Entries []SecretEntry
}

SecretsResult holds the outcome of GetSecrets. Exactly one of Raw or Entries is populated, depending on which format was requested: Raw holds the verbatim dotenv text when format was ".env"; Entries holds the decoded array for JSON mode.