governance

type AccessReason struct {
	Code    ReasonCode
	Message string
}

type CustomerAccess struct {
	// Customer the matched identifiers resolved to.
	Customer customer.Customer
	// Matched lists the request identifiers (customer key or usage-attribution subject
	// key) that resolved to this customer.
	Matched []string
	// Features maps feature key to its access status.
	Features map[string]FeatureAccess
	// UpdatedAt is the time the access state was evaluated.
	UpdatedAt time.Time
}

type FeatureAccess struct {
	HasAccess bool
	// Reason is set when HasAccess is false.
	Reason *AccessReason
}

type QueryAccessInput struct {
	Namespace string
	// CustomerKeys are arbitrary identifiers — each a customer key or a usage-attribution
	// subject key. Identifiers that cannot be resolved are reported in QueryResult.Errors.
	CustomerKeys []string
	// FeatureKeys, when non-empty, restricts evaluation to those feature keys. When empty,
	// every non-archived feature in the namespace is evaluated.
	FeatureKeys []string
	// IncludeCredits requests credit-balance evaluation. Not yet implemented.
	IncludeCredits bool

	// Pagination over the resolved customers (sorted by CreatedAt, ID). At most one of
	// After/Before may be set.
	PageSize int
	After    *pagination.Cursor
	Before   *pagination.Cursor
}

type QueryError struct {
	// CustomerKey is the request identifier that produced this error.
	CustomerKey string
	Code        QueryErrorCode
	Message     string
}

type QueryErrorCode string

type QueryResult struct {
	// Customers are the access evaluations for the current page, ordered by (CreatedAt, ID).
	Customers []CustomerAccess
	// Errors are partial errors for unresolved input identifiers.
	Errors []QueryError

	// HasPrev/HasNext indicate adjacent pages relative to the current one.
	HasPrev bool
	HasNext bool
	// First/Last are the cursors of the first and last item on the current page.
	First *pagination.Cursor
	Last  *pagination.Cursor
}

type ReasonCode string

type Service interface {
	QueryAccess(ctx context.Context, input QueryAccessInput) (QueryResult, error)
}