provider

type AuthScheme struct {
	Type string `json:"type"           yaml:"type"`           // bearer | basic | apikey | oauth2
	In   string `json:"in,omitempty"   yaml:"in,omitempty"`   // header | query (apikey)
	Name string `json:"name,omitempty" yaml:"name,omitempty"` // header/query name (apikey)

	// oauth2 specifics (Type == oauth2). The access token clic obtains from these
	// is applied as a bearer token, so oauth2 reuses the bearer code path.
	Flow     string   `json:"flow,omitempty"      yaml:"flow,omitempty"`      // client_credentials | authorization_code
	AuthURL  string   `json:"auth_url,omitempty"  yaml:"auth_url,omitempty"`  // authorization endpoint (authorization_code)
	TokenURL string   `json:"token_url,omitempty" yaml:"token_url,omitempty"` // token endpoint
	Scopes   []string `json:"scopes,omitempty"    yaml:"scopes,omitempty"`    // requested scopes
}

type Describer interface {
	Summary() string
}

type Inputs struct {
	// Scalars maps a section key ("path", "query", "header") to that section's
	// field name/value pairs.
	Scalars map[string]map[string]any

	// Body is the assembled request body, when the command builds one from
	// discrete fields.
	Body map[string]any

	// RawBody, when non-empty, is used verbatim as the request body instead of
	// Body (raw-body commands and the studio's raw editing mode).
	RawBody string
}

type Interactive interface {
	// Sections returns the input sections to render, in display order. A nil or
	// empty result means the command takes no interactive input and can be run
	// immediately.
	Sections() []Section

	// Execute runs the command with the collected inputs and returns a result.
	Execute(ctx context.Context, in Inputs) (*Result, error)
}

type Options struct {
	Server      string
	Interactive bool
	Token       string
	Username    string
	Password    string
	APIKey      string

	// oauth2 credentials and overrides
	ClientID     string
	ClientSecret string
	Scopes       []string
	OAuthFlow    string // override the grant flow when a spec declares several
	RedirectURL  string // loopback redirect for the authorization-code flow
}

type Parameter struct {
	Name        string `json:"name"                  yaml:"name"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Type        string `json:"type"                  yaml:"type"`
	Required    bool   `json:"required"              yaml:"required"`
	Default     any    `json:"default,omitempty"     yaml:"default,omitempty"`
	AsFlag      string `json:"as_flag,omitempty"     yaml:"as_flag,omitempty"`
	// contains filtered or unexported fields
}

type ParameterSet []*Parameter

type Previewer interface {
	Preview(ctx context.Context, in Inputs) (*RequestPreview, error)
}

type Provider interface {
	// Configure wires the provider's positional arguments, flags, and run
	// behavior onto the given cobra command.
	Configure(cmd *cobra.Command)
	Type() string
	Validate() error
}

type RequestPreview struct {
	// Kind selects how the preview is rendered: an HTTP request (method, URL,
	// headers, body) or a plain textual invocation.
	Kind ResultKind

	// Method, URL, Headers, and Body describe an HTTP request (ResultHTTP). Body
	// is nil when the request carries no meaningful payload.
	Method  string
	URL     string
	Headers http.Header
	Body    []byte

	// Display is a one-line rendering of a non-HTTP invocation (ResultText),
	// e.g. "git status" or "invoke arn:aws:… {\"id\":1}".
	Display string

	// CLIArgs are the positional arguments and flags that, appended after the
	// command's path, reproduce this request from the headless clic CLI.
	CLIArgs []string
}

type Result struct {
	// Kind selects how the result is displayed.
	Kind ResultKind

	// RequestLine summarizes what was sent (e.g. "GET https://api/pets/42").
	RequestLine string

	// Status is the HTTP status code (ResultHTTP) or process exit code
	// (ResultText). Zero means "not applicable".
	Status int

	// Latency is the wall-clock time the execution took.
	Latency time.Duration

	// Headers are the HTTP response headers (ResultHTTP only).
	Headers http.Header

	// ContentType is the response's content type, when known.
	ContentType string

	// Body is the raw response body or captured output.
	Body []byte
}

type ResultKind string

type Section struct {
	// Key routes collected values back to the provider ("path", "query",
	// "header", "body").
	Key string

	// Title is the human-facing heading shown above the section.
	Title string

	// Fields are the inputs in the section, in display order.
	Fields []form.Field

	// Raw marks a body section whose value is entered as a single block of
	// freeform text (e.g. raw JSON) rather than as discrete fields.
	Raw bool
}