gitprovider

type Client interface {
	// The Client allows accessing all known resources.
	ResourceClient

	// SupportedDomain returns the domain endpoint for this client, e.g. "github.com", "gitlab.com" or
	// "my-custom-git-server.com:6443". This allows a higher-level user to know what Client to use for
	// what endpoints.
	// This field is set at client creation time, and can't be changed.
	SupportedDomain() string

	// ProviderID returns the provider ID (e.g. "github", "gitlab") for this client.
	// This field is set at client creation time, and can't be changed.
	ProviderID() ProviderID

	// Raw returns the Go client used under the hood to access the Git provider.
	Raw() interface{}
}

type CreatableInfo interface {
	// ValidateInfo validates the object at {Object}.Set() and POST-time, before defaulting.
	// Set (non-nil) and required fields should be validated.
	ValidateInfo() error
	// Default will be run after validation, setting optional pointer fields to their
	// default values before doing the POST request
	Default()
}

type DeployKey interface {
	// DeployKey implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// The deploy key can be updated.
	GenericUpdatable
	// The deploy key can be reconciled.
	GenericReconcilable
	// The deploy key can be deleted.
	GenericDeletable
	// RepositoryBound returns repository reference details.
	RepositoryBound

	// Get returns high-level information about this deploy key.
	Get() DeployKeyInfo
	// Set sets high-level desired state for this deploy key. In order to apply these changes in
	// the Git provider, run .Update() or .Reconcile().
	Set(DeployKeyInfo) error
}

type DeployKeyClient interface {
	// Get gets a DeployKey by its name.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, name string) (DeployKey, error)

	// List lists all deploy keys of the given credential type.
	//
	// List returns all available deploy keys for the given type,
	// using multiple paginated requests if needed.
	List(ctx context.Context) ([]DeployKey, error)

	// Create creates a deploy key with the given specifications.
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, req DeployKeyInfo) (DeployKey, error)

	// Reconcile makes sure req is the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, req DeployKeyInfo) (resp DeployKey, actionTaken bool, err error)
}

type DeployKeyInfo struct {
	// Name is the human-friendly interpretation of what the key is for (and does)
	// +required
	Name string `json:"name"`

	// Key specifies the public part of the deploy (e.g. SSH) key
	// +required
	Key []byte `json:"key"`

	// ReadOnly specifies whether this DeployKey can write to the repository or not
	// Default value at POST-time: true
	// +optional
	ReadOnly *bool `json:"readOnly,omitempty"`
}

type GenericDeletable interface {
	// Delete deletes the current resource irreversebly.
	//
	// ErrNotFound is returned if the resource doesn't exist anymore.
	Delete(ctx context.Context) error
}

type GenericReconcilable interface {
	// Reconcile makes sure the desired state in this object (called "req" here) becomes
	// the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	//
	// The internal API object will be overridden with the received server data if actionTaken == true.
	Reconcile(ctx context.Context) (actionTaken bool, err error)
}

type GenericUpdatable interface {
	// Update will apply the desired state in this object to the server.
	// Only set fields will be respected (i.e. PATCH behaviour).
	// In order to apply changes to this object, use the .Set({Resource}Info) error
	// function, or cast .APIObject() to a pointer to the provider-specific type
	// and set custom fields there.
	//
	// ErrNotFound is returned if the resource does not exist.
	//
	// The internal API object will be overridden with the received server data.
	Update(ctx context.Context) error
}

type HTTPError struct {
	// HTTP response that caused this error.
	Response *http.Response `json:"-"`
	// Full error message, human-friendly and formatted
	ErrorMessage string `json:"errorMessage"`
	// Message about what happened
	Message string `json:"message"`
	// Where to find more information about the error
	DocumentationURL string `json:"documentationURL"`
}

type IdentityRef interface {
	// IdentityRef implements ValidateTarget so it can easily be validated as a field
	validation.ValidateTarget

	// GetDomain returns the URL-domain for the Git provider backend,
	// e.g. "github.com" or "self-hosted-gitlab.com:6443"
	GetDomain() string

	// GetIdentity returns the user account name or a slash-separated path of the
	// <organization-name>[/<sub-organization-name>...] form. This can be used as
	// an identifier for this specific actor in the system.
	GetIdentity() string

	// GetType returns what type of identity this instance represents. If IdentityTypeUser is returned
	// this IdentityRef can safely be casted to an UserRef. If any of IdentityTypeOrganization or
	// IdentityTypeSuborganization are returned, this IdentityRef can be casted to a OrganizationRef.
	GetType() IdentityType

	// String returns the HTTPS URL, and implements fmt.Stringer
	String() string
}

type IdentityType string

type InvalidCredentialsError struct {
	// InvalidCredentialsError extends HTTPError
	HTTPError `json:",inline"`
}

type LicenseTemplate string

type Object interface {
	// APIObject returns the underlying value that was returned from the server
	APIObject() interface{}
}

type OrgRepositoriesClient interface {
	// Get returns the repository at the given path.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, r OrgRepositoryRef) (OrgRepository, error)

	// List all repositories in the given organization.
	//
	// List returns all available repositories, using multiple paginated requests if needed.
	List(ctx context.Context, o OrganizationRef) ([]OrgRepository, error)

	// Create creates a repository for the given organization, with the data and options
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, r OrgRepositoryRef, req RepositoryInfo, opts ...RepositoryCreateOption) (OrgRepository, error)

	// Reconcile makes sure req is the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, r OrgRepositoryRef, req RepositoryInfo, opts ...RepositoryReconcileOption) (resp OrgRepository, actionTaken bool, err error)
}

type OrgRepository interface {
	// OrgRepository is a superset of UserRepository.
	UserRepository

	// TeamAccess returns a client for operating on the teams that have access to this specific repository.
	TeamAccess() TeamAccessClient
}

type OrgRepositoryRef struct {
	// OrgRepositoryRef embeds OrganizationRef inline.
	OrganizationRef `json:",inline"`

	// RepositoryName specifies the Git repository name. This field is URL-friendly,
	// e.g. "kubernetes" or "cluster-api-provider-aws"
	// +required
	RepositoryName string `json:"repositoryName"`
}

type Organization interface {
	// Organization implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// OrganizationBound returns organization reference details.
	OrganizationBound

	// Get returns high-level information about the organization.
	Get() OrganizationInfo

	// Teams gives access to the TeamsClient for this specific organization
	Teams() TeamsClient
}

type OrganizationBound interface {
	// Organization returns the OrganizationRef associated with this object.
	Organization() OrganizationRef
}

type OrganizationInfo struct {
	// Name is the human-friendly name of this organization, e.g. "Flux" or "Kubernetes SIGs"
	Name *string `json:"name"`

	// Description returns a description for the organization
	Description *string `json:"description"`
}

type OrganizationRef struct {
	// Domain returns e.g. "github.com", "gitlab.com" or a custom domain like "self-hosted-gitlab.com" (GitLab)
	// The domain _might_ contain port information, in the form of "host:port", if applicable
	// +required
	Domain string `json:"domain"`

	// Organization specifies the URL-friendly, lowercase name of the organization or user account name,
	// e.g. "fluxcd" or "kubernetes-sigs".
	// +required
	Organization string `json:"organization"`

	// SubOrganizations point to optional sub-organizations (or sub-groups) of the given top-level organization
	// in the Organization field. E.g. "gitlab.com/fluxcd/engineering/frontend" would yield ["engineering", "frontend"]
	// +optional
	SubOrganizations []string `json:"subOrganizations,omitempty"`
}

type OrganizationsClient interface {
	// Get a specific organization the user has access to.
	// This might also refer to a sub-organization.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, o OrganizationRef) (Organization, error)

	// List all top-level organizations the specific user has access to.
	//
	// List returns all available organizations, using multiple paginated requests if needed.
	List(ctx context.Context) ([]Organization, error)

	// Children returns the immediate child-organizations for the specific OrganizationRef o.
	// The OrganizationRef may point to any existing sub-organization.
	//
	// This is not supported in GitHub.
	//
	// Children returns all available organizations, using multiple paginated requests if needed.
	Children(ctx context.Context, o OrganizationRef) ([]Organization, error)
}

type ProviderID string

type RateLimitError struct {
	// RateLimitError extends HTTPError
	HTTPError `json:",inline"`

	// The number of requests per hour the client is currently limited to.
	Limit int `json:"limit"`
	// The number of remaining requests the client can make this hour.
	Remaining int `json:"remaining"`
	// The timestamp at which point the current rate limit will reset.
	Reset time.Time `json:"reset"`
}

type RepositoryBound interface {
	// Repository returns the RepositoryRef associated with this object.
	Repository() RepositoryRef
}

type RepositoryCreateOption interface {
	// ApplyToRepositoryCreateOptions should apply relevant options to the target
	ApplyToRepositoryCreateOptions(target *RepositoryCreateOptions)
}

type RepositoryCreateOptions struct {
	// AutoInit can be set to true in order to automatically initialize the Git repo with a
	// README.md and optionally a license in the first commit.
	// Default: nil (which means "false, don't create")
	AutoInit *bool

	// LicenseTemplate lets the user specify a license template to use when AutoInit is true
	// Default: nil
	// Available options: See the LicenseTemplate enum
	LicenseTemplate *LicenseTemplate
}

type RepositoryInfo struct {
	// Description returns a description for the repository
	// No default value at POST-time
	// +optional
	Description *string `json:"description"`

	// DefaultBranch describes the default branch for the given repository. This has
	// historically been "master" (and is as of writing still the Git default), but is
	// expected to be changed to e.g. "main" shortly in the future.
	// Default value at POST-time: master (but this can and will change in future library versions!)
	// +optional
	DefaultBranch *string `json:"defaultBranch"`

	// Visibility returns the desired visibility for the repository
	// Default value at POST-time: RepositoryVisibilityPrivate
	// +optional
	Visibility *RepositoryVisibility `json:"visibility"`
}

type RepositoryPermission string

type RepositoryReconcileOption interface {
	// RepositoryCreateOption is embedded, as reconcile uses the create options
	RepositoryCreateOption
}

type RepositoryRef interface {
	// RepositoryRef is a superset of IdentityRef.
	IdentityRef

	// GetRepository returns the repository name for this repo.
	GetRepository() string

	// GetCloneURL gets the clone URL for the specified transport type.
	GetCloneURL(transport TransportType) string
}

type RepositoryVisibility string

type ResourceClient interface {
	// Organizations returns the OrganizationsClient handling sets of organizations.
	Organizations() OrganizationsClient

	// OrgRepositories returns the OrgRepositoriesClient handling sets of repositories in an organization.
	OrgRepositories() OrgRepositoriesClient

	// UserRepositories returns the UserRepositoriesClient handling sets of repositories for a user.
	UserRepositories() UserRepositoriesClient
}

type Team interface {
	// Team implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// OrganizationBound returns organization reference details.
	OrganizationBound

	// Get returns high-level information about this team.
	Get() TeamInfo
}

type TeamAccess interface {
	// TeamAccess implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// The deploy key can be updated.
	GenericUpdatable
	// The deploy key can be reconciled.
	GenericReconcilable
	// The deploy key can be deleted.
	GenericDeletable
	// RepositoryBound returns repository reference details.
	RepositoryBound

	// Get returns high-level information about this team access for the repository.
	Get() TeamAccessInfo
	// Set sets high-level desired state for this team access object. In order to apply these changes in
	// the Git provider, run .Update() or .Reconcile().
	Set(TeamAccessInfo) error
}

type TeamAccessClient interface {
	// Get gets a TeamAccess by its name.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, name string) (TeamAccess, error)

	// List lists the team access control list for this repository.
	//
	// List returns all available team access lists, using multiple paginated requests if needed.
	List(ctx context.Context) ([]TeamAccess, error)

	// Create adds a given team to the repo's team access control list.
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, req TeamAccessInfo) (TeamAccess, error)

	// Reconcile makes sure req is the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, req TeamAccessInfo) (resp TeamAccess, actionTaken bool, err error)
}

type TeamAccessInfo struct {
	// Name describes the name of the team. The team name may contain slashes
	// +required
	Name string `json:"name"`

	// Permission describes the permission level for which the team is allowed to operate
	// Default: pull
	// Available options: See the RepositoryPermission enum
	// +optional
	Permission *RepositoryPermission `json:"permission,omitempty"`
}

type TeamInfo struct {
	// Name describes the name of the team. The team name may contain slashes.
	Name string `json:"name"`

	// Members points to a set of user names (logins) of the members of this team.
	Members []string `json:"members"`
}

type TeamsClient interface {
	// Get a team within the specific organization.
	//
	// name may include slashes, but must not be an empty string.
	// Teams are sub-groups in GitLab.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, name string) (Team, error)

	// List all teams (recursively, in terms of subgroups) within the specific organization.
	//
	// List returns all available organizations, using multiple paginated requests if needed.
	List(ctx context.Context) ([]Team, error)
}

type TransportType string

type UserRef struct {
	// Domain returns e.g. "github.com", "gitlab.com" or a custom domain like "self-hosted-gitlab.com" (GitLab)
	// The domain _might_ contain port information, in the form of "host:port", if applicable
	// +required
	Domain string `json:"domain"`

	// UserLogin returns the user account login name.
	// +required
	UserLogin string `json:"userLogin"`
}

type UserRepositoriesClient interface {
	// Get returns the repository at the given path.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, r UserRepositoryRef) (UserRepository, error)

	// List all repositories for the given user.
	//
	// List returns all available repositories, using multiple paginated requests if needed.
	List(ctx context.Context, o UserRef) ([]UserRepository, error)

	// Create creates a repository for the given user, with the data and options
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, r UserRepositoryRef, req RepositoryInfo, opts ...RepositoryCreateOption) (UserRepository, error)

	// Reconcile makes sure req is the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, r UserRepositoryRef, req RepositoryInfo, opts ...RepositoryReconcileOption) (resp UserRepository, actionTaken bool, err error)
}

type UserRepository interface {
	// UserRepository and OrgRepository implement the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// The repository can be updated.
	GenericUpdatable
	// The repository can be reconciled.
	GenericReconcilable
	// The repository can be deleted.
	GenericDeletable
	// RepositoryBound returns repository reference details.
	RepositoryBound

	// Get returns high-level information about this repository.
	Get() RepositoryInfo
	// Set sets high-level desired state for this repository. In order to apply these changes in
	// the Git provider, run .Update() or .Reconcile().
	Set(RepositoryInfo) error

	// DeployKeys gives access to manipulating deploy keys to access this specific repository.
	DeployKeys() DeployKeyClient
}

type UserRepositoryRef struct {
	// UserRepositoryRef embeds UserRef inline.
	UserRef `json:",inline"`

	// RepositoryName specifies the Git repository name. This field is URL-friendly,
	// e.g. "kubernetes" or "cluster-api-provider-aws"
	// +required
	RepositoryName string `json:"repositoryName"`
}

type ValidationError struct {
	// RateLimitError extends HTTPError
	HTTPError `json:",inline"`

	// Errors contain context about what validation(s) failed
	Errors []ValidationErrorItem `json:"errors"`
}

type ValidationErrorItem struct {
	// Resource on which the error occurred
	Resource string `json:"resource"`
	// Field on which the error occurred
	Field string `json:"field"`
	// Code for the validation error
	Code string `json:"code"`
	// Message describing the error. Errors with Code == "custom" will always have this set.
	Message string `json:"message"`
}