provider

type Capabilities struct {
	Kinds                []ItemKind
	SupportsReleases     bool
	SupportsObjectives   bool
	SupportsCustomFields bool
	SupportsWrite        bool
}

type CustomField struct {
	Key   string
	Name  string
	Value any
	Type  string
}

type CustomFieldDefinition struct {
	ID             string
	Key            string
	Name           string
	Type           string
	AppliesToKinds []ItemKind
	Metadata       map[string]any
}

type GetItemRequest struct {
	Kind ItemKind
	ID   string // the source system's own ID or reference
}

type Item struct {
	// ID is a canonical, globally-unique identifier: "<provider>:<source id>".
	ID       string
	Provider string
	SourceID string
	// SourceRef is the source system's own human-facing reference (e.g. an
	// Aha reference number like "SE-2"), where one exists.
	SourceRef string
	// SourceURL links back to the record in the source system's own UI.
	SourceURL string
	// WorkspaceRef is the source system's human-facing workspace/project
	// reference when available (e.g. an Aha product reference prefix).
	WorkspaceRef string

	Kind        ItemKind
	Name        string
	Description string

	Status   *Status
	Progress *float64 // normalized 0-100; nil if the provider doesn't track it

	// ParentID is the canonical ID of a parent Item, if this item has one
	// (e.g. a feature's initiative, or an initiative's epic).
	ParentID string
	// ReleaseID is the canonical ID of an associated Release, if any.
	ReleaseID string

	StartDate *time.Time
	DueDate   *time.Time
	CreatedAt *time.Time
	UpdatedAt *time.Time

	Owner        *Person
	Tags         []string
	CustomFields []CustomField
	Links        []Link

	// MoSCoW is an optional prioritization level: must_have, should_have,
	// could_have, or wont_have; "" = unset. Like RICE, it isn't populated
	// by adapters (no PM tool exposes it as a first-class API field) — a
	// downstream custom-field mapping layer fills it per tenant.
	MoSCoW string
	// Kano is an optional Kano Model classification: must-be, performance,
	// attractive, indifferent, reverse, or questionable (prism-roadmap's
	// vocabulary); "" = unset. Like MoSCoW, adapters don't populate it — it
	// comes from a downstream mapping or augmentation layer.
	Kano string
	// RICE holds optional RICE prioritization inputs; nil = not provided.
	RICE *RICE

	// Metadata holds provider-specific fields with no canonical equivalent.
	// Keys should be namespaced by provider, e.g. "aha.progress_source".
	Metadata map[string]any
}

type ItemKind string

type Link struct {
	Type  string
	URL   string
	Title string
}

type ListCustomFieldDefinitionsRequest struct {
	Kind ItemKind // empty means definitions for all kinds
}

type ListCustomFieldDefinitionsResponse struct {
	Definitions []CustomFieldDefinition
}

type ListItemsRequest struct {
	Kinds   []ItemKind // empty means all kinds the provider supports
	Page    int
	PerPage int
}

type ListItemsResponse struct {
	Items      []Item
	Page       int
	PerPage    int
	TotalCount int
}

type ListReleasesRequest struct {
	Page    int
	PerPage int
}

type ListReleasesResponse struct {
	Releases   []Release
	Page       int
	PerPage    int
	TotalCount int
}

type ListStatusesRequest struct {
	Kind ItemKind // empty means statuses for all kinds
}

type ListStatusesResponse struct {
	Statuses []Status
}

type Person struct {
	ID    string
	Name  string
	Email string
}

type Provider interface {
	// Name returns a short, stable identifier for this provider (e.g. "aha",
	// "productboard"), used as the Provider field on canonical types and as
	// the registry key.
	Name() string

	// Close releases any resources held by the provider (HTTP clients,
	// connections, etc.).
	Close() error

	// Capabilities reports what this provider actually supports.
	Capabilities() Capabilities

	ListItems(ctx context.Context, req *ListItemsRequest) (*ListItemsResponse, error)
	GetItem(ctx context.Context, req *GetItemRequest) (*Item, error)
	ListReleases(ctx context.Context, req *ListReleasesRequest) (*ListReleasesResponse, error)
	ListStatuses(ctx context.Context, req *ListStatusesRequest) (*ListStatusesResponse, error)
	ListCustomFieldDefinitions(ctx context.Context, req *ListCustomFieldDefinitionsRequest) (*ListCustomFieldDefinitionsResponse, error)
}

type RICE struct {
	Reach      *float64
	Impact     *float64
	Confidence *float64
	Effort     *float64
	// Score is a precomputed RICE score, if the source provides one.
	// Consumers typically recompute (Reach × Impact × Confidence) / Effort
	// when it's nil.
	Score *float64
}

type Release struct {
	ID        string
	Provider  string
	SourceID  string
	SourceRef string
	SourceURL string

	Name string

	StartDate   *time.Time
	ReleaseDate *time.Time
	Released    bool

	Status   *Status
	Progress *float64

	Metadata map[string]any
}

type Status struct {
	ID       string
	Name     string
	Category StatusCategory
	Complete bool
	Color    string
	Position int64
}

type StatusCategory string