entitlement

type Access struct {
	// Map of featureKey to entitlement value + ID
	Entitlements map[string]EntitlementValueWithId
}

type AlreadyDeletedError struct {
	EntitlementID string
}

type AlreadyExistsError struct {
	EntitlementID string
	FeatureID     string
	CustomerID    string
}

type BalanceHistoryWindow struct {
	From           time.Time
	To             time.Time
	UsageInPeriod  float64
	BalanceAtStart float64
	OverageAtStart float64
}

type CreateCustomerEntitlementGrantInput struct {
	CustomerID    customer.CustomerID
	EntitlementID string
	Grant         CreateEntitlementGrantInputs
}

type CreateCustomerEntitlementInput struct {
	CustomerID  customer.CustomerID
	Entitlement CreateEntitlementInputs
	Grants      []CreateEntitlementGrantInputs
}

type CreateEntitlementGrantInputs struct {
	credit.CreateGrantInput
}

type CreateEntitlementInputs struct {
	Namespace        string                             `json:"namespace"`
	FeatureID        *string                            `json:"featureId"`
	FeatureKey       *string                            `json:"featureKey"`
	UsageAttribution streaming.CustomerUsageAttribution `json:"usageAttribution"`
	EntitlementType  EntitlementType                    `json:"type"`
	Metadata         map[string]string                  `json:"metadata,omitempty"`
	Annotations      models.Annotations                 `json:"annotations,omitempty"`

	// ActiveFrom allows entitlements to be scheduled for future activation.
	// If not set, the entitlement is active immediately.
	ActiveFrom *time.Time `json:"activeFrom,omitempty"`
	// ActiveTo allows entitlements to be descheduled for future activation.
	// If not set, the entitlement is active until deletion.
	ActiveTo *time.Time `json:"activeTo,omitempty"`

	MeasureUsageFrom        *MeasureUsageFromInput `json:"measureUsageFrom,omitempty"`
	IssueAfterReset         *float64               `json:"issueAfterReset,omitempty"`
	IssueAfterResetPriority *uint8                 `json:"issueAfterResetPriority,omitempty"`
	IsSoftLimit             *bool                  `json:"isSoftLimit,omitempty"`
	Config                  *string                `json:"config,omitempty"`
	UsagePeriod             *UsagePeriodInput      `json:"usagePeriod,omitempty"`
	PreserveOverageAtReset  *bool                  `json:"preserveOverageAtReset,omitempty"`

	// UnitConfig is the rate card's UnitConfig snapshotted onto the entitlement at
	// subscription time. The metered grant-owner adapter uses it to convert usage
	// into billing units at balance-check time (OM-400). It is the typed DTO from the
	// leaf unitconfig package (not productcatalog) so this package, which sits below
	// productcatalog in the import graph, can reference it without a cycle. Only
	// metered entitlements created from a unit_config rate card carry it; nil means
	// balances are computed in raw metered units, as before.
	UnitConfig *unitconfig.UnitConfig `json:"unitConfig,omitempty"`

	SubscriptionManaged bool `json:"subscriptionManaged,omitempty"`
}

type CreateEntitlementRepoInputs struct {
	Namespace        string                             `json:"namespace"`
	FeatureID        string                             `json:"featureId"`
	FeatureKey       string                             `json:"featureKey"`
	UsageAttribution streaming.CustomerUsageAttribution `json:"usageAttribution"`
	EntitlementType  EntitlementType                    `json:"type"`
	Metadata         map[string]string                  `json:"metadata,omitempty"`
	ActiveFrom       *time.Time                         `json:"activeFrom,omitempty"`
	ActiveTo         *time.Time                         `json:"activeTo,omitempty"`

	Annotations models.Annotations `json:"annotations,omitempty"`

	MeasureUsageFrom        *time.Time             `json:"measureUsageFrom,omitempty"`
	IssueAfterReset         *float64               `json:"issueAfterReset,omitempty"`
	IssueAfterResetPriority *uint8                 `json:"issueAfterResetPriority,omitempty"`
	IsSoftLimit             *bool                  `json:"isSoftLimit,omitempty"`
	Config                  *string                `json:"config,omitempty"`
	UnitConfig              *unitconfig.UnitConfig `json:"unitConfig,omitempty"`
	UsagePeriod             *UsagePeriodInput      `json:"usagePeriod,omitempty"`
	CurrentUsagePeriod      *timeutil.ClosedPeriod `json:"currentUsagePeriod,omitempty"`
	PreserveOverageAtReset  *bool                  `json:"preserveOverageAtReset,omitempty"`
}

type CustomerEntitlementAPIService interface {
	CreateCustomerEntitlement(ctx context.Context, input CreateCustomerEntitlementInput) (*Entitlement, error)
	OverrideCustomerEntitlement(ctx context.Context, input OverrideCustomerEntitlementInput) (*Entitlement, error)
	GetCustomerEntitlementHistory(ctx context.Context, input GetCustomerEntitlementHistoryInput) (CustomerEntitlementHistory, error)
	GetCustomerEntitlement(ctx context.Context, input GetCustomerEntitlementInput) (*Entitlement, error)
	ListCustomerEntitlements(ctx context.Context, input ListCustomerEntitlementsInput) (pagination.Result[Entitlement], error)
	ResetCustomerEntitlementUsage(ctx context.Context, input ResetCustomerEntitlementUsageInput) error
	DeleteCustomerEntitlement(ctx context.Context, input DeleteCustomerEntitlementInput) error
	ListCustomerEntitlementGrants(ctx context.Context, input ListCustomerEntitlementGrantsInput) (pagination.Result[grant.Grant], error)
	CreateCustomerEntitlementGrant(ctx context.Context, input CreateCustomerEntitlementGrantInput) (grant.Grant, error)
}

type CustomerEntitlementAccess struct {
	FeatureKey string
	Type       EntitlementType
	Value      EntitlementValue
}

type CustomerEntitlementAccessAPIService interface {
	GetCustomerEntitlementAccess(ctx context.Context, input GetCustomerEntitlementAccessInput) (CustomerEntitlementAccess, error)
	ListCustomerEntitlementAccess(ctx context.Context, input ListCustomerEntitlementAccessInput) ([]CustomerEntitlementAccess, error)
}

type CustomerEntitlementHistory struct {
	Windows  []BalanceHistoryWindow
	Burndown engine.GrantBurnDownHistory
}

type DeleteCustomerEntitlementInput struct {
	CustomerID    customer.CustomerID
	EntitlementID string
}

type Entitlement struct {
	GenericProperties

	// All none-core fields are optional
	// metered
	MeasureUsageFrom        *time.Time `json:"measureUsageFrom,omitempty"`
	IssueAfterReset         *float64   `json:"issueAfterReset,omitempty"`
	IssueAfterResetPriority *uint8     `json:"issueAfterResetPriority,omitempty"`
	IsSoftLimit             *bool      `json:"isSoftLimit,omitempty"`
	LastReset               *time.Time `json:"lastReset,omitempty"`
	PreserveOverageAtReset  *bool      `json:"preserveOverageAtReset,omitempty"`

	// static
	Config *string `json:"config,omitempty"`

	// UnitConfig is the rate card's UnitConfig snapshotted onto the entitlement
	// (metered entitlements only). See CreateEntitlementInputs.UnitConfig.
	UnitConfig *unitconfig.UnitConfig `json:"unitConfig,omitempty"`
}

type EntitlementAPIService interface {
	GetEntitlementByID(ctx context.Context, input GetEntitlementByIDInput) (*Entitlement, error)
	ListNamespaceEntitlements(ctx context.Context, input ListNamespaceEntitlementsInput) (pagination.Result[Entitlement], error)
}

type EntitlementCreatedEventV2 entitlementEventV2

type EntitlementDeletedEventV2 entitlementEventV2

type EntitlementRepo interface {
	// GetActiveEntitlementOfSubjectAt returns the active entitlement of a customer at a given time by feature key
	GetActiveEntitlementOfCustomerAt(ctx context.Context, namespace string, customerID string, featureKey string, at time.Time) (*Entitlement, error)

	// GetScheduledEntitlements returns all scheduled entitlements for a given customer-feature pair that become inactive after the given time, sorted by the time they become active
	GetScheduledEntitlements(ctx context.Context, namespace string, customerID string, featureKey string, starting time.Time) ([]Entitlement, error)

	// DeactivateEntitlement deactivates an entitlement by setting the activeTo time. If the entitlement is already deactivated, it returns an error.
	DeactivateEntitlement(ctx context.Context, entitlementID models.NamespacedID, at time.Time) error

	CreateEntitlement(ctx context.Context, entitlement CreateEntitlementRepoInputs) (*Entitlement, error)
	GetEntitlement(ctx context.Context, entitlementID models.NamespacedID) (*Entitlement, error)
	DeleteEntitlement(ctx context.Context, entitlementID models.NamespacedID, at time.Time) error

	ListEntitlements(ctx context.Context, params ListEntitlementsParams) (pagination.Result[Entitlement], error)

	// ListNamespacesWithActiveEntitlements returns a list of namespaces that have active entitlements
	//
	// Active in this context means the entitlement is active at any point between now and the given time.
	// If includeDeletedAfter is before the current time, it will include namespaces that have entitlements active at that instance.
	ListNamespacesWithActiveEntitlements(ctx context.Context, includeDeletedAfter time.Time) ([]string, error)

	UpdateEntitlementUsagePeriod(ctx context.Context, entitlementID models.NamespacedID, params UpdateEntitlementUsagePeriodParams) error

	// ListActiveEntitlementsWithExpiredUsagePeriod returns a list of active entitlements with usage period that expired before the highwatermark
	// - Only entitlements active at the highwatermark are considered.
	// - The list is sorted by the current usage period end, then by created at, then by id.
	// - The list is paginated by the cursor & limit.
	// - CurrentUsagePeriod won't be mapped to the calculated values
	ListActiveEntitlementsWithExpiredUsagePeriod(ctx context.Context, params ListExpiredEntitlementsParams) ([]Entitlement, error)

	// UpsertEntitlementCurrentPeriods upserts the current usage period for a list of entitlements
	// - If an entitlement is found, it will be updated
	// - If any update fails, the entire operation will fail
	UpsertEntitlementCurrentPeriods(ctx context.Context, updates []UpsertEntitlementCurrentPeriodElement) error

	LockEntitlementForTx(ctx context.Context, tx *entutils.TxDriver, entitlementID models.NamespacedID, wait bool) error

	entutils.TxCreator
}

type EntitlementType string

type EntitlementValue interface {
	HasAccess() bool
}

type EntitlementValueWithId struct {
	Type  EntitlementType
	Value EntitlementValue
	ID    string
}

type EntitlementWithCustomer struct {
	Entitlement
	Customer customer.Customer
}

type ForbiddenError struct {
	Message string
}

type GenericProperties struct {
	models.NamespacedModel
	models.ManagedModel
	models.MetadataModel
	models.Annotations

	// ActiveFrom allows entitlements to be scheduled for future activation.
	// If not set, the entitlement is active immediately.
	ActiveFrom *time.Time `json:"activeFrom,omitempty"`
	// ActiveTo allows entitlements to be descheduled for future activation.
	// If not set, the entitlement is active until deletion.
	ActiveTo *time.Time `json:"activeTo,omitempty"`

	ID         string `json:"id,omitempty"`
	FeatureID  string `json:"featureId,omitempty"`
	FeatureKey string `json:"featureKey,omitempty"`

	CustomerID string `json:"customerId,omitempty"`

	EntitlementType           EntitlementType        `json:"type,omitempty"`
	UsagePeriod               *UsagePeriod           `json:"usagePeriod,omitempty"`
	CurrentUsagePeriod        *timeutil.ClosedPeriod `json:"currentUsagePeriod,omitempty"`
	OriginalUsagePeriodAnchor *time.Time             `json:"originalUsagePeriodAnchor,omitempty"`
}

type GetCustomerEntitlementAccessInput struct {
	CustomerID    customer.CustomerID
	FeatureKey    string
	EntitlementID string
	At            time.Time
}

type GetCustomerEntitlementHistoryInput struct {
	CustomerID    customer.CustomerID
	EntitlementID string
	From          *time.Time
	To            *time.Time
	WindowSize    meter.WindowSize
	TimeZone      *time.Location
}

type GetCustomerEntitlementInput struct {
	CustomerID    customer.CustomerID
	EntitlementID string
}

type GetEntitlementByIDInput struct {
	Namespace     string
	EntitlementID string
}

type GrantAPIService interface {
	ListNamespaceGrants(ctx context.Context, input ListNamespaceGrantsInput) (pagination.Result[grant.Grant], error)
	VoidGrant(ctx context.Context, input VoidGrantInput) error
}

type InvalidFeatureError struct {
	FeatureID string
	Message   string
}

type InvalidValueError struct {
	Message string
	Type    EntitlementType
}

type ListCustomerEntitlementAccessInput struct {
	CustomerID customer.CustomerID
}

type ListCustomerEntitlementGrantsInput struct {
	CustomerID    customer.CustomerID
	EntitlementID string

	IncludeDeleted bool

	OrderBy grant.OrderBy
	Order   sortx.Order
	Page    pagination.Page
}

type ListCustomerEntitlementsInput struct {
	CustomerID customer.CustomerID

	FeatureID  *filter.FilterULID
	FeatureKey *filter.FilterString
	Type       *filter.FilterString

	OrderBy ListEntitlementsOrderBy
	Order   sortx.Order
	Page    pagination.Page
}

type ListEntitlementsOrderBy string

type ListEntitlementsParams struct {
	IDs              []string
	Namespaces       []string
	SubjectKeys      []string
	CustomerIDs      []string
	CustomerKeys     []string
	FeatureIDs       []string
	FeatureKeys      []string
	FeatureIDsOrKeys []string
	EntitlementTypes []EntitlementType

	CustomerID      *filter.FilterULID
	FeatureID       *filter.FilterULID
	FeatureKey      *filter.FilterString
	EntitlementType *filter.FilterString

	OrderBy ListEntitlementsOrderBy
	Order   sortx.Order
	// TODO[galexi]: We should clean up how these 4 fields are used together.
	IncludeDeleted      bool
	IncludeDeletedAfter time.Time
	ExcludeInactive     bool
	ActiveAt            *time.Time

	Page pagination.Page
	// will be deprecated
	Limit int
	// will be deprecated
	Offset int
}

type ListEntitlementsWithCustomerResult struct {
	Entitlements  pagination.Result[Entitlement]
	CustomersByID map[models.NamespacedID]*customer.Customer
}

type ListExpiredEntitlementsParams struct {
	Namespaces    []string
	Highwatermark time.Time
	Limit         int
	// Cursor is the ID of the last entitlement in the previous page
	// If not provided, the query will return the first page of results
	Cursor *paginationv2.Cursor
}

type ListNamespaceEntitlementsInput struct {
	Namespace string

	CustomerID *filter.FilterULID
	FeatureID  *filter.FilterULID
	FeatureKey *filter.FilterString
	Type       *filter.FilterString

	OrderBy ListEntitlementsOrderBy
	Order   sortx.Order
	Page    pagination.Page
}

type ListNamespaceGrantsInput struct {
	Namespace      string
	IncludeDeleted bool

	CustomerID *filter.FilterULID
	FeatureID  *filter.FilterULID

	OrderBy grant.OrderBy
	Order   sortx.Order
	Page    pagination.Page
}

type MeasureUsageFromEnum string

type MeasureUsageFromInput struct {
	// contains filtered or unexported fields
}

type NoAccessValue struct{}

type NotFoundError struct {
	EntitlementID models.NamespacedID
}

type OverrideCustomerEntitlementInput struct {
	CustomerID    customer.CustomerID
	EntitlementID string
	Entitlement   CreateEntitlementInputs
	Grants        []CreateEntitlementGrantInputs
}

type ResetCustomerEntitlementUsageInput struct {
	CustomerID      customer.CustomerID
	EntitlementID   string
	EffectiveAt     *time.Time
	RetainAnchor    bool
	PreserveOverage *bool
}

type Service interface {
	models.ServiceHooks[Entitlement]

	// Facade interfaces provide convenience helpers for the API layer.
	CustomerEntitlementAccessAPIService
	CustomerEntitlementAPIService
	EntitlementAPIService
	GrantAPIService

	// Meant for API use primarily
	CreateEntitlement(ctx context.Context, input CreateEntitlementInputs, grants []CreateEntitlementGrantInputs) (*Entitlement, error)
	// OverrideEntitlement replaces a currently active entitlement with a new one.
	OverrideEntitlement(ctx context.Context, customerID string, entitlementIdOrFeatureKey string, input CreateEntitlementInputs, grants []CreateEntitlementGrantInputs) (*Entitlement, error)

	ScheduleEntitlement(ctx context.Context, input CreateEntitlementInputs) (*Entitlement, error)
	// SupersedeEntitlement replaces an entitlement by scheduling a new one
	SupersedeEntitlement(ctx context.Context, entitlementId string, input CreateEntitlementInputs) (*Entitlement, error)

	GetEntitlement(ctx context.Context, namespace string, id string) (*Entitlement, error)
	GetEntitlementWithCustomer(ctx context.Context, namespace string, id string) (*EntitlementWithCustomer, error)
	DeleteEntitlement(ctx context.Context, namespace string, id string, at time.Time) error

	GetEntitlementValue(ctx context.Context, namespace string, customerID string, idOrFeatureKey string, at time.Time) (EntitlementValue, error)

	GetEntitlementsOfCustomer(ctx context.Context, namespace string, customerId string, at time.Time) ([]Entitlement, error)
	ListEntitlements(ctx context.Context, params ListEntitlementsParams) (pagination.Result[Entitlement], error)
	ListEntitlementsWithCustomer(ctx context.Context, params ListEntitlementsParams) (ListEntitlementsWithCustomerResult, error)

	// Attempts to get the entitlement in an ambiguous situation where it's unclear if the entitlement is referenced by ID or FeatureKey + CustomerID.
	// First attempts to resolve by ID, then by FeatureKey + CustomerID.
	//
	// For consistency, it is forbidden for entitlements to be created for featueres the keys of which could be mistaken for entitlement IDs.
	GetEntitlementOfCustomerAt(ctx context.Context, namespace string, customerID string, idOrFeatureKey string, at time.Time) (*Entitlement, error)

	// GetAccess returns the access of a customer.
	// It returns a map of featureKey to entitlement value + ID.
	GetAccess(ctx context.Context, namespace string, customerID string) (Access, error)
}

type SubTypeConnector interface {
	GetValue(ctx context.Context, entitlement *Entitlement, at time.Time) (EntitlementValue, error)

	// Runs before creating the entitlement, building the Repository inputs.
	// If it returns an error the operation has to fail.
	BeforeCreate(entitlement CreateEntitlementInputs, feature feature.Feature) (*CreateEntitlementRepoInputs, error)

	// Runs after entitlement creation.
	// If it returns an error the operation has to fail.
	AfterCreate(ctx context.Context, entitlement *Entitlement) error
}

type TypedEntitlement interface {
	GetType() EntitlementType
}

type UniquenessConstraintError struct {
	E1, E2 Entitlement
}

type UpdateEntitlementUsagePeriodParams struct {
	CurrentUsagePeriod timeutil.ClosedPeriod
}

type UpsertEntitlementCurrentPeriodElement struct {
	models.NamespacedID
	CurrentUsagePeriod timeutil.ClosedPeriod
}

type UsagePeriod struct {
	// contains filtered or unexported fields
}

type UsagePeriodInput = timeutil.Timed[timeutil.Recurrence]

type VoidGrantInput struct {
	GrantID models.NamespacedID
	At      *time.Time
}

type WrongTypeError struct {
	Expected EntitlementType
	Actual   EntitlementType
}