providers

type ConversionObserver interface {
	BeginToRC(function string, native any) ConversionSnapshot
	EndToRC(function string, before ConversionSnapshot, nativeAfter any, result models.Records, err error)
	BeginToNative(function string, records models.Records) ConversionSnapshot
	EndToNative(function string, before ConversionSnapshot, recordsAfter models.Records, result any, err error)
}

type ConversionSnapshot any

type CreateOption func(*CreateOptions)

type CreateOptions struct {
	ConversionObserver ConversionObserver
	// RequestedRole is set by the typed factory after caller options are applied.
	// It is exactly KindDNS or KindRegistrar for runtime instances.
	RequestedRole ProviderKind
}

type CredsField struct {
	// Key is the exact name of the field as it should appear inside the
	// creds.json provider entry (for example "apitoken" or "KeyId").
	Key string
	// Label is the human readable text shown when prompting.
	Label string
	// Help is a short sentence explaining the field.
	Help string
	// Secret masks the input when prompting. Ignored when Multiline is
	// also set, since the external editor does not mask input.
	Secret bool
	// Multiline opens the user's $EDITOR so values like PEM blocks with
	// embedded newlines can be entered in full.
	Multiline bool
	// Required makes the init command reject an empty value.
	Required bool
	// Default suggests a value. Presented as the pre filled answer.
	Default string
	// EnvVar, when set, is used as the default if the environment variable is
	// present. It overrides Default.
	EnvVar string
	// Choices restricts input to one of the listed values.
	Choices []string
	// ConfirmValue asks a yes/no question and stores this value on yes.
	ConfirmValue string
	// Validator can reject an entered value with an explanatory error.
	Validator func(string) error
	// Internal marks the field as a UI selector whose answer drives
	// ShowIf logic on later fields. Internal answers are not written to
	// creds.json.
	//
	// Convention: prefix the Key with an underscore (for example
	// "_authMethod") so it is visually distinct from real creds.json
	// keys when reading metadata registrations.
	Internal bool
	// ShowIf restricts when this field is shown. Each entry maps an
	// earlier field's Key to the value that must be selected for this
	// field to appear. An empty map means always show.
	ShowIf map[string]string
}

type DNSServiceProvider interface {
	models.DNSProvider
}

type Definition struct {
	// FriendlyName is the brand name ("Google", not "GCLOUD")
	FriendlyName string

	// Maintainer is the github username of the maintainer.
	Maintainer string

	// Aliases (optional) is an optional list of aliases. For example, if
	// we rename CLOUDFLAREAPI to CLOUDFLARE, we would make CLOUDFLAREAPI an alias to
	// support legacy configurations.
	Aliases []string

	// SupportedTypes is an exhaustive, required declaration of record support.
	// List Basic8 (A, AAAA, CAA, CNAME, MX, NS, SRV, TXT) explicitly when
	// supported. A non-nil empty slice declares no record support. Nil still
	// resolves to Basic8 for compatibility, but provider registrations must
	// supply a list. Entries may use TYPE:Status:Reason
	// to attach a comment to Can, Cannot, or Unimplemented status. A trailing
	// ": http(s)://..." in Reason supplies a link.
	// Internal commands such as IMPORT_TRANSFORM do not belong in this list.
	SupportedTypes []string

	// OfficiallySupported documents if the provider has official support.
	// Omit it for the default, Cannot() without a reason.
	OfficiallySupported *DocumentationNote

	// DefaultTTL (optional) minimum TTL when `get-zone` writes .js files
	DefaultTTL uint32

	// CanAutoDNSSEC defaults to Cannot(). Declare Can() or Unimplemented()
	// to document a different status, or Cannot(reason) to explain the default.
	CanAutoDNSSEC *DocumentationNote
	// CanConcur defaults to Can(). Declare Cannot() for providers that must
	// not be used concurrently. Unimplemented() is invalid for this field.
	CanConcur *DocumentationNote
	// CanDualHost defaults to Can(). Declare Cannot() or Unimplemented()
	// when the provider cannot manage apex NS records for dual hosting, or
	// Can(reason) to explain support that needs qualification.
	CanDualHost *DocumentationNote
	// CanUseDSForChildren defaults to no child-DS support unless SupportedTypes
	// grants general DS support, which also grants child-DS support.
	CanUseDSForChildren *DocumentationNote

	// Interface discovery sets the capabilities; these reasons explain the result.
	CanGetZonesReason   string
	CreateDomainsReason string
	// RecordIdentity optionally distinguishes records with the same label,
	// type, and RDATA when the provider stores them as separate objects.
	RecordIdentity RecordIdentityFunc

	// CredFields is a description of the creds.json fields for this provider. Used by "init".
	CredFields []CredsField

	// DocsURL optionally overrides https://docs.dnscontrol.org/provider/<lowercase name>
	// for legacy documentation paths. An override matching the default is an error.
	// Register fills an empty value with the default URL.
	DocsURL string
	// VendorAPIDocURL optionally links to the vendor's API documentation.
	VendorAPIDocURL string
	// PortalURL points to where a user can obtain API credentials.
	PortalURL string
	// Notes is optional onboarding text shown before prompting for credentials.
	Notes string
	// PostWrite prepares local resources after the wizard writes creds.json.
	PostWrite func(map[string]string) error

	// Calculated by Register and Finalize. Providers must leave these fields unset.
	TypeName           string // ex. "BIND"
	ImplementationType reflect.Type
	Initializer        Initializer  // Function called to initialize a client
	Kind               ProviderKind // Are we initializing a REgistrar or DNS Provider?
	RecordAuditor      RecordAuditor
	CanGetZones        bool
	DocCreateDomains   bool
	// contains filtered or unexported fields
}

type DocumentationNote struct {
	HasFeature    bool
	Unimplemented bool
	Comment       string
	Link          string
}

type InitializableProvider interface {
	Initialize(map[string]string, json.RawMessage, *CreateOptions) error
}

type Initializer func(map[string]string, json.RawMessage, *CreateOptions) (any, error)

type None struct{}

type ProviderKind uint8

type RecordAuditor func(models.Records) []error

type RecordIdentityFunc func(*models.RecordConfig) string

type Registrar interface {
	models.Registrar
}

type ZoneCreator interface {
	EnsureZoneExists(dc *models.DomainConfig) error
}

type ZoneLister interface {
	ListZones() ([]string, error)
}