// Code generated by @openmeter/typespec-go. DO NOT EDIT.

package openmeter

import (
	"encoding/json"
	"fmt"
	"time"
)

// Addon reference.
type AddonReference struct {
	ID string `json:"id"`
}

// Address
type Address struct {
	// Country code in [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html)
	// alpha-2 format.
	Country *string `json:"country,omitempty"`
	// Postal code.
	PostalCode *string `json:"postal_code,omitempty"`
	// State or province.
	State *string `json:"state,omitempty"`
	// City.
	City *string `json:"city,omitempty"`
	// First line of the address.
	Line1 *string `json:"line1,omitempty"`
	// Second line of the address.
	Line2 *string `json:"line2,omitempty"`
	// Phone number.
	PhoneNumber *string `json:"phone_number,omitempty"`
}

// App reference.
type AppReference struct {
	// The ID of the app.
	ID string `json:"id"`
}

// The type of the app.
type AppType string

const (
	AppTypeSandbox           AppType = "sandbox"
	AppTypeStripe            AppType = "stripe"
	AppTypeExternalInvoicing AppType = "external_invoicing"
)

func (value AppType) Valid() bool {
	switch value {
	case AppTypeSandbox, AppTypeStripe, AppTypeExternalInvoicing:
		return true
	default:
		return false
	}
}

// Fiat or custom currency code.
type BillingCurrencyCode string

// A period with defined start and end dates.
//
// The period is always inclusive at the start and exclusive at the end.
type ClosedPeriod struct {
	// The start of the period.
	//
	// The period is inclusive at the start.
	From time.Time `json:"from"`
	// The end of the period.
	//
	// The period is exclusive at the end.
	To time.Time `json:"to"`
}

// Collection method specifies how the invoice should be collected (automatic or
// manual).
type CollectionMethod string

const (
	CollectionMethodChargeAutomatically CollectionMethod = "charge_automatically"
	CollectionMethodSendInvoice         CollectionMethod = "send_invoice"
)

func (value CollectionMethod) Valid() bool {
	switch value {
	case CollectionMethodChargeAutomatically, CollectionMethodSendInvoice:
		return true
	default:
		return false
	}
}

// Cursor pagination metadata.
type CursorMeta struct {
	// Page metadata.
	Page CursorMetaPage `json:"page"`
}

// Cursor pagination metadata.
type CursorMetaPage struct {
	// URI to the first page.
	First *string `json:"first,omitempty"`
	// URI to the last page.
	Last *string `json:"last,omitempty"`
	// URI to the next page.
	Next Nullable[string] `json:"next"`
	// URI to the previous page.
	Previous Nullable[string] `json:"previous"`
	// Requested page size.
	Size int64 `json:"size"`
}

// Determines which page of the collection to retrieve.
type CursorPaginationQueryPage struct {
	// The number of items to include per page.
	Size *int64 `json:"size,omitempty"`
	// Request the next page of data, starting with the item after this parameter.
	After *string `json:"after,omitempty"`
	// Request the previous page of data, starting with the item before this parameter.
	Before *string `json:"before,omitempty"`
}

// Customers can be individuals or organizations that can subscribe to plans and
// have access to features.
type Customer struct {
	ID string `json:"id"`
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	// An ISO-8601 timestamp representation of entity creation date.
	CreatedAt time.Time `json:"created_at"`
	// An ISO-8601 timestamp representation of entity last update date.
	UpdatedAt time.Time `json:"updated_at"`
	// An ISO-8601 timestamp representation of entity deletion date.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	Key       string     `json:"key"`
	// Mapping to attribute metered usage to the customer by the event subject.
	UsageAttribution *CustomerUsageAttribution `json:"usage_attribution,omitempty"`
	// The primary email address of the customer.
	PrimaryEmail *string `json:"primary_email,omitempty"`
	// Currency of the customer. Used for billing, tax and invoicing.
	Currency *string `json:"currency,omitempty"`
	// The billing address of the customer. Used for tax and invoicing.
	BillingAddress *Address `json:"billing_address,omitempty"`
}

// Mapping to attribute metered usage to the customer. One customer can have zero
// or more subjects, but one subject can only belong to one customer.
type CustomerUsageAttribution struct {
	// The subjects that are attributed to the customer. Can be empty when no usage
	// event subjects are associated with the customer.
	SubjectKeys []string `json:"subject_keys"`
}

// The type of the entitlement.
type EntitlementType string

const (
	EntitlementTypeMetered EntitlementType = "metered"
	EntitlementTypeStatic  EntitlementType = "static"
	EntitlementTypeBoolean EntitlementType = "boolean"
)

func (value EntitlementType) Valid() bool {
	switch value {
	case EntitlementTypeMetered, EntitlementTypeStatic, EntitlementTypeBoolean:
		return true
	default:
		return false
	}
}

// Feature reference.
type FeatureReference struct {
	ID string `json:"id"`
}

// Identifies whether a resource lifecycle is controlled by OpenMeter or manually
// overridden by the API user.
//
// Values:
//
// - `system`: The resource lifecycle is controlled by OpenMeter.
// - `manual`: The resource lifecycle was manually overridden by the API user.
type LifecycleController string

const (
	LifecycleControllerSystem LifecycleController = "system"
	LifecycleControllerManual LifecycleController = "manual"
)

func (value LifecycleController) Valid() bool {
	switch value {
	case LifecycleControllerSystem, LifecycleControllerManual:
		return true
	default:
		return false
	}
}

// Filters to apply to a meter query.
type MeterQueryFilters struct {
	// Filters to apply to the dimensions of the query. For `subject` and `customer_id`
	// only equals ("eq", "in") comparisons are supported.
	Dimensions *map[string]QueryFilterStringMapItemInput `json:"dimensions,omitempty"`
}

// The granularity of the time grouping. Time durations are specified in ISO 8601
// format.
type MeterQueryGranularity string

const (
	MeterQueryGranularityMinute MeterQueryGranularity = "PT1M"
	MeterQueryGranularityHour   MeterQueryGranularity = "PT1H"
	MeterQueryGranularityDay    MeterQueryGranularity = "P1D"
	MeterQueryGranularityMonth  MeterQueryGranularity = "P1M"
)

func (value MeterQueryGranularity) Valid() bool {
	switch value {
	case MeterQueryGranularityMinute, MeterQueryGranularityHour, MeterQueryGranularityDay, MeterQueryGranularityMonth:
		return true
	default:
		return false
	}
}

// A meter query request.
type MeterQueryRequest struct {
	// The start of the period the usage is queried from.
	From *time.Time `json:"from,omitempty"`
	// The end of the period the usage is queried to.
	To *time.Time `json:"to,omitempty"`
	// The size of the time buckets to group the usage into. If not specified, the
	// usage is aggregated over the entire period.
	Granularity *MeterQueryGranularity `json:"granularity,omitempty"`
	// The value is the name of the time zone as defined in the IANA Time Zone Database
	// (http://www.iana.org/time-zones). The time zone is used to determine the start
	// and end of the time buckets. If not specified, the UTC timezone will be used.
	TimeZone *string `json:"time_zone,omitempty"`
	// The dimensions to group the results by.
	GroupByDimensions *[]string `json:"group_by_dimensions,omitempty"`
	// Filters to apply to the query.
	Filters *MeterQueryFilters `json:"filters,omitempty"`
}

// A collection of addresses for the party.
type PartyAddresses struct {
	// Billing address.
	BillingAddress Address `json:"billing_address"`
}

// Identity stores the details required to identify an entity for tax purposes in a
// specific country.
type PartyTaxIdentity struct {
	// Normalized tax identification code shown on the original identity document.
	Code *string `json:"code,omitempty"`
}

// Price.
//
// Price is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the PriceFrom* constructors.
// The exported Type field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.
type Price struct {
	Type string `json:"type"`
	raw  json.RawMessage
}

func (u *Price) UnmarshalJSON(data []byte) error {
	u.raw = append([]byte(nil), data...)
	if string(data) == "null" {
		u.Type = ""
		return nil
	}

	var envelope struct {
		Value string `json:"type"`
	}
	if err := json.Unmarshal(data, &envelope); err != nil {
		return err
	}
	u.Type = envelope.Value
	return nil
}

func (u Price) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

func (u Price) AsPriceFree() (*PriceFree, error) {
	if u.Type != "free" {
		return nil, fmt.Errorf("Price: expected type %q, got %q", "free", u.Type)
	}
	var value PriceFree
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func PriceFromPriceFree(value PriceFree) (Price, error) {
	value.Type = "free"
	raw, err := json.Marshal(value)
	if err != nil {
		return Price{}, err
	}
	var result Price
	if err := result.UnmarshalJSON(raw); err != nil {
		return Price{}, err
	}
	return result, nil
}

func (u Price) AsPriceFlat() (*PriceFlat, error) {
	if u.Type != "flat" {
		return nil, fmt.Errorf("Price: expected type %q, got %q", "flat", u.Type)
	}
	var value PriceFlat
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func PriceFromPriceFlat(value PriceFlat) (Price, error) {
	value.Type = "flat"
	raw, err := json.Marshal(value)
	if err != nil {
		return Price{}, err
	}
	var result Price
	if err := result.UnmarshalJSON(raw); err != nil {
		return Price{}, err
	}
	return result, nil
}

func (u Price) AsPriceUnit() (*PriceUnit, error) {
	if u.Type != "unit" {
		return nil, fmt.Errorf("Price: expected type %q, got %q", "unit", u.Type)
	}
	var value PriceUnit
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func PriceFromPriceUnit(value PriceUnit) (Price, error) {
	value.Type = "unit"
	raw, err := json.Marshal(value)
	if err != nil {
		return Price{}, err
	}
	var result Price
	if err := result.UnmarshalJSON(raw); err != nil {
		return Price{}, err
	}
	return result, nil
}

func (u Price) AsPriceGraduated() (*PriceGraduated, error) {
	if u.Type != "graduated" {
		return nil, fmt.Errorf("Price: expected type %q, got %q", "graduated", u.Type)
	}
	var value PriceGraduated
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func PriceFromPriceGraduated(value PriceGraduated) (Price, error) {
	value.Type = "graduated"
	raw, err := json.Marshal(value)
	if err != nil {
		return Price{}, err
	}
	var result Price
	if err := result.UnmarshalJSON(raw); err != nil {
		return Price{}, err
	}
	return result, nil
}

func (u Price) AsPriceVolume() (*PriceVolume, error) {
	if u.Type != "volume" {
		return nil, fmt.Errorf("Price: expected type %q, got %q", "volume", u.Type)
	}
	var value PriceVolume
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func PriceFromPriceVolume(value PriceVolume) (Price, error) {
	value.Type = "volume"
	raw, err := json.Marshal(value)
	if err != nil {
		return Price{}, err
	}
	var result Price
	if err := result.UnmarshalJSON(raw); err != nil {
		return Price{}, err
	}
	return result, nil
}

// Flat price.
type PriceFlat struct {
	// The type of the price.
	Type PriceType `json:"type"`
	// The amount of the flat price.
	Amount Numeric `json:"amount"`
}

// Free price.
type PriceFree struct {
	// The type of the price.
	Type PriceType `json:"type"`
}

// Graduated tiered price.
//
// Each tier's rate applies only to the usage within that tier. Pricing can change
// as cumulative usage crosses tier boundaries.
//
// When UnitConfig is present on the rate card, tier boundaries (up_to_amount) are
// expressed in converted billing units.
type PriceGraduated struct {
	// The type of the price.
	Type PriceType `json:"type"`
	// The tiers of the graduated price. At least one tier is required.
	Tiers []PriceTier `json:"tiers"`
}

// The payment term of a flat price.
type PricePaymentTerm string

const (
	PricePaymentTermInAdvance PricePaymentTerm = "in_advance"
	PricePaymentTermInArrears PricePaymentTerm = "in_arrears"
)

func (value PricePaymentTerm) Valid() bool {
	switch value {
	case PricePaymentTermInAdvance, PricePaymentTermInArrears:
		return true
	default:
		return false
	}
}

// A price tier used in graduated and volume pricing.
//
// At least one price component (flat_price or unit_price) must be set. When
// UnitConfig is present on the rate card, up_to_amount is expressed in converted
// billing units.
type PriceTier struct {
	// Up to and including this quantity will be contained in the tier. If undefined,
	// the tier is open-ended (the last tier).
	UpToAmount *Numeric `json:"up_to_amount,omitempty"`
	// The flat price component of the tier. Charged once when the tier is entered.
	FlatPrice *PriceFlat `json:"flat_price,omitempty"`
	// The unit price component of the tier. Charged per billing unit within the tier.
	UnitPrice *PriceUnit `json:"unit_price,omitempty"`
}

// The type of the price.
//
// - `free`: No charge, the rate card is included at no cost.
// - `flat`: A fixed amount charged once per billing period, regardless of usage.
// - `unit`: A fixed rate charged per billing unit consumed.
// - `graduated`: Tiered pricing where each tier's rate applies only to usage
// within that tier.
// - `volume`: Tiered pricing where the rate for the highest tier reached applies
// to all units in the period.
type PriceType string

const (
	PriceTypeFree      PriceType = "free"
	PriceTypeFlat      PriceType = "flat"
	PriceTypeUnit      PriceType = "unit"
	PriceTypeGraduated PriceType = "graduated"
	PriceTypeVolume    PriceType = "volume"
)

func (value PriceType) Valid() bool {
	switch value {
	case PriceTypeFree, PriceTypeFlat, PriceTypeUnit, PriceTypeGraduated, PriceTypeVolume:
		return true
	default:
		return false
	}
}

// Unit price.
//
// Charges a fixed rate per billing unit. When UnitConfig is present on the rate
// card, billing units are the converted quantities (e.g. GB instead of bytes).
type PriceUnit struct {
	// The type of the price.
	Type PriceType `json:"type"`
	// The amount of the unit price.
	Amount Numeric `json:"amount"`
}

// Volume tiered price.
//
// The maximum quantity within a period determines the per-unit price for all units
// in that period.
//
// When UnitConfig is present on the rate card, tier boundaries (up_to_amount) are
// expressed in converted billing units.
type PriceVolume struct {
	// The type of the price.
	Type PriceType `json:"type"`
	// The tiers of the volume price. At least one tier is required.
	Tiers []PriceTier `json:"tiers"`
}

// Validation errors providing detailed description of the issue.
type ProductCatalogValidationError struct {
	// Machine-readable error code.
	Code string `json:"code"`
	// Human-readable description of the error.
	Message string `json:"message"`
	// Additional structured context.
	Attributes map[string]any `json:"attributes,omitempty"`
	// The path to the field.
	Field string `json:"field"`
}

// Billing profile reference.
type ProfileReference struct {
	// The ID of the billing profile.
	ID string `json:"id"`
}

// A query filter for a string attribute. Operators are mutually exclusive, only
// one operator is allowed at a time.
type QueryFilterString struct {
	// The attribute equals the provided value.
	Eq *string `json:"eq,omitempty"`
	// The attribute does not equal the provided value.
	Neq *string `json:"neq,omitempty"`
	// The attribute is one of the provided values.
	In []string `json:"in,omitempty"`
	// The attribute is not one of the provided values.
	Nin []string `json:"nin,omitempty"`
	// The attribute contains the provided value.
	Contains *string `json:"contains,omitempty"`
	// The attribute does not contain the provided value.
	Ncontains *string `json:"ncontains,omitempty"`
	// Combines the provided filters with a logical AND.
	And []QueryFilterString `json:"and,omitempty"`
	// Combines the provided filters with a logical OR.
	Or []QueryFilterString `json:"or,omitempty"`
}

// A query filter for a string attribute. Operators are mutually exclusive, only
// one operator is allowed at a time.
type QueryFilterStringInput struct {
	// The attribute equals the provided value.
	Eq *string `json:"eq,omitempty"`
	// The attribute does not equal the provided value.
	Neq *string `json:"neq,omitempty"`
	// The attribute is one of the provided values.
	In *[]string `json:"in,omitempty"`
	// The attribute is not one of the provided values.
	Nin *[]string `json:"nin,omitempty"`
	// The attribute contains the provided value.
	Contains *string `json:"contains,omitempty"`
	// The attribute does not contain the provided value.
	Ncontains *string `json:"ncontains,omitempty"`
	// Combines the provided filters with a logical AND.
	And *[]QueryFilterStringInput `json:"and,omitempty"`
	// Combines the provided filters with a logical OR.
	Or *[]QueryFilterStringInput `json:"or,omitempty"`
}

// A query filter for an item in a string map attribute. Operators are mutually
// exclusive, only one operator is allowed at a time.
type QueryFilterStringMapItem struct {
	// The attribute exists.
	Exists *bool `json:"exists,omitempty"`
	// The attribute equals the provided value.
	Eq *string `json:"eq,omitempty"`
	// The attribute does not equal the provided value.
	Neq *string `json:"neq,omitempty"`
	// The attribute is one of the provided values.
	In []string `json:"in,omitempty"`
	// The attribute is not one of the provided values.
	Nin []string `json:"nin,omitempty"`
	// The attribute contains the provided value.
	Contains *string `json:"contains,omitempty"`
	// The attribute does not contain the provided value.
	Ncontains *string `json:"ncontains,omitempty"`
	// Combines the provided filters with a logical AND.
	And []QueryFilterString `json:"and,omitempty"`
	// Combines the provided filters with a logical OR.
	Or []QueryFilterString `json:"or,omitempty"`
}

// A query filter for an item in a string map attribute. Operators are mutually
// exclusive, only one operator is allowed at a time.
type QueryFilterStringMapItemInput struct {
	// The attribute exists.
	Exists *bool `json:"exists,omitempty"`
	// The attribute equals the provided value.
	Eq *string `json:"eq,omitempty"`
	// The attribute does not equal the provided value.
	Neq *string `json:"neq,omitempty"`
	// The attribute is one of the provided values.
	In *[]string `json:"in,omitempty"`
	// The attribute is not one of the provided values.
	Nin *[]string `json:"nin,omitempty"`
	// The attribute contains the provided value.
	Contains *string `json:"contains,omitempty"`
	// The attribute does not contain the provided value.
	Ncontains *string `json:"ncontains,omitempty"`
	// Combines the provided filters with a logical AND.
	And *[]QueryFilterStringInput `json:"and,omitempty"`
	// Combines the provided filters with a logical OR.
	Or *[]QueryFilterStringInput `json:"or,omitempty"`
}

// A rate card defines the pricing and entitlement of a feature or service.
type RateCard struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string           `json:"description,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	Key         string            `json:"key"`
	// The feature associated with the rate card.
	Feature *FeatureReference `json:"feature,omitempty"`
	// The billing cadence of the rate card. When null, the charge is one-time
	// (non-recurring). Only valid for flat prices.
	BillingCadence *string `json:"billing_cadence,omitempty"`
	// The price of the rate card.
	Price Price `json:"price"`
	// Unit conversion configuration for the rate card.
	//
	// Synthesized on read for plans authored with v1 dynamic or package prices:
	// dynamic prices map to a unit price with a multiply unit config, and package
	// prices map to a unit price with a divide unit config.
	//
	// Accepted on create and update only when the UnitConfig feature is enabled on the
	// deployment; otherwise rejected.
	UnitConfig *UnitConfig `json:"unit_config,omitempty"`
	// The payment term of the rate card. In advance payment term can only be used for
	// flat prices.
	PaymentTerm *PricePaymentTerm `json:"payment_term,omitempty"`
	// Spend commitments for this rate card. Only applicable to usage-based prices
	// (unit, graduated, volume).
	Commitments *SpendCommitments `json:"commitments,omitempty"`
	// The discounts of the rate card.
	Discounts *RateCardDiscounts `json:"discounts,omitempty"`
	// The tax config of the rate card.
	TaxConfig *RateCardTaxConfig `json:"tax_config,omitempty"`
	// The entitlement template granted to subscribers of a plan or addon containing
	// this rate card. Requires `feature` to be set.
	Entitlement *RateCardEntitlement `json:"entitlement,omitempty"`
}

// A rate card defines the pricing and entitlement of a feature or service.
type RateCardInput struct {
	// Display name of the resource.
	//
	// Between 1 and 256 characters.
	Name string `json:"name"`
	// Optional description of the resource.
	//
	// Maximum 1024 characters.
	Description *string            `json:"description,omitempty"`
	Labels      *map[string]string `json:"labels,omitempty"`
	Key         string             `json:"key"`
	// The feature associated with the rate card.
	Feature *FeatureReference `json:"feature,omitempty"`
	// The billing cadence of the rate card. When null, the charge is one-time
	// (non-recurring). Only valid for flat prices.
	BillingCadence *string `json:"billing_cadence,omitempty"`
	// The price of the rate card.
	Price Price `json:"price"`
	// Unit conversion configuration for the rate card.
	//
	// Synthesized on read for plans authored with v1 dynamic or package prices:
	// dynamic prices map to a unit price with a multiply unit config, and package
	// prices map to a unit price with a divide unit config.
	//
	// Accepted on create and update only when the UnitConfig feature is enabled on the
	// deployment; otherwise rejected.
	UnitConfig *UnitConfig `json:"unit_config,omitempty"`
	// The payment term of the rate card. In advance payment term can only be used for
	// flat prices.
	PaymentTerm *PricePaymentTerm `json:"payment_term,omitempty"`
	// Spend commitments for this rate card. Only applicable to usage-based prices
	// (unit, graduated, volume).
	Commitments *SpendCommitments `json:"commitments,omitempty"`
	// The discounts of the rate card.
	Discounts *RateCardDiscounts `json:"discounts,omitempty"`
	// The tax config of the rate card.
	TaxConfig *RateCardTaxConfig `json:"tax_config,omitempty"`
	// The entitlement template granted to subscribers of a plan or addon containing
	// this rate card. Requires `feature` to be set.
	Entitlement *RateCardEntitlement `json:"entitlement,omitempty"`
}

// The entitlement template of a boolean entitlement.
type RateCardBooleanEntitlement struct {
	// The type of the entitlement template.
	Type EntitlementType `json:"type"`
}

// Discount configuration for a rate card.
type RateCardDiscounts struct {
	// Percentage discount applied to the price (0–100).
	Percentage *float64 `json:"percentage,omitempty"`
	// Number of usage units granted free before billing starts. Only applies to
	// usage-based lines (not flat fees). Usage is treated as zero until this amount is
	// exhausted.
	Usage *Numeric `json:"usage,omitempty"`
}

// Entitlement template configured on a rate card. The feature is taken from the
// rate card itself, so it is omitted here.
//
// RateCardEntitlement is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the RateCardEntitlementFrom* constructors.
// The exported Type field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.
type RateCardEntitlement struct {
	Type string `json:"type"`
	raw  json.RawMessage
}

func (u *RateCardEntitlement) UnmarshalJSON(data []byte) error {
	u.raw = append([]byte(nil), data...)
	if string(data) == "null" {
		u.Type = ""
		return nil
	}

	var envelope struct {
		Value string `json:"type"`
	}
	if err := json.Unmarshal(data, &envelope); err != nil {
		return err
	}
	u.Type = envelope.Value
	return nil
}

func (u RateCardEntitlement) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

func (u RateCardEntitlement) AsRateCardMeteredEntitlement() (*RateCardMeteredEntitlement, error) {
	if u.Type != "metered" {
		return nil, fmt.Errorf("RateCardEntitlement: expected type %q, got %q", "metered", u.Type)
	}
	var value RateCardMeteredEntitlement
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func RateCardEntitlementFromRateCardMeteredEntitlement(value RateCardMeteredEntitlement) (RateCardEntitlement, error) {
	value.Type = "metered"
	raw, err := json.Marshal(value)
	if err != nil {
		return RateCardEntitlement{}, err
	}
	var result RateCardEntitlement
	if err := result.UnmarshalJSON(raw); err != nil {
		return RateCardEntitlement{}, err
	}
	return result, nil
}

func (u RateCardEntitlement) AsRateCardStaticEntitlement() (*RateCardStaticEntitlement, error) {
	if u.Type != "static" {
		return nil, fmt.Errorf("RateCardEntitlement: expected type %q, got %q", "static", u.Type)
	}
	var value RateCardStaticEntitlement
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func RateCardEntitlementFromRateCardStaticEntitlement(value RateCardStaticEntitlement) (RateCardEntitlement, error) {
	value.Type = "static"
	raw, err := json.Marshal(value)
	if err != nil {
		return RateCardEntitlement{}, err
	}
	var result RateCardEntitlement
	if err := result.UnmarshalJSON(raw); err != nil {
		return RateCardEntitlement{}, err
	}
	return result, nil
}

func (u RateCardEntitlement) AsRateCardBooleanEntitlement() (*RateCardBooleanEntitlement, error) {
	if u.Type != "boolean" {
		return nil, fmt.Errorf("RateCardEntitlement: expected type %q, got %q", "boolean", u.Type)
	}
	var value RateCardBooleanEntitlement
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func RateCardEntitlementFromRateCardBooleanEntitlement(value RateCardBooleanEntitlement) (RateCardEntitlement, error) {
	value.Type = "boolean"
	raw, err := json.Marshal(value)
	if err != nil {
		return RateCardEntitlement{}, err
	}
	var result RateCardEntitlement
	if err := result.UnmarshalJSON(raw); err != nil {
		return RateCardEntitlement{}, err
	}
	return result, nil
}

// The entitlement template of a metered entitlement.
type RateCardMeteredEntitlement struct {
	// The type of the entitlement template.
	Type EntitlementType `json:"type"`
	// If soft limit is true, the subject can use the feature even if the entitlement
	// is exhausted; access remains granted.
	IsSoftLimit *bool `json:"is_soft_limit,omitempty"`
	// The amount of usage granted each usage period, in the feature's unit. Usage is
	// counted against this allowance and the balance resets every usage period. When
	// `is_soft_limit` is true the subject keeps access after the limit is reached;
	// otherwise access is denied once the allowance is exhausted.
	Limit *float64 `json:"limit,omitempty"`
	// The reset interval of the metered entitlement in ISO8601 format. Defaults to the
	// billing cadence of the rate card.
	UsagePeriod *string `json:"usage_period,omitempty"`
}

// The entitlement template of a static entitlement.
type RateCardStaticEntitlement struct {
	// The type of the entitlement template.
	Type EntitlementType `json:"type"`
	// The entitlement config as a JSON object. Returned when checking entitlement
	// access; useful for configuring fine-grained access settings implemented in your
	// own system.
	Config any `json:"config"`
}

// The tax config of the rate card.
type RateCardTaxConfig struct {
	Behavior *TaxBehavior     `json:"behavior,omitempty"`
	Code     TaxCodeReference `json:"code"`
}

// Settlement mode for billing.
//
// Values:
//
// - `credit_then_invoice`: Credits are applied first, then any remainder is
// invoiced.
// - `credit_only`: Usage is settled exclusively against credits.
type SettlementMode string

const (
	SettlementModeCreditThenInvoice SettlementMode = "credit_then_invoice"
	SettlementModeCreditOnly        SettlementMode = "credit_only"
)

func (value SettlementMode) Valid() bool {
	switch value {
	case SettlementModeCreditThenInvoice, SettlementModeCreditOnly:
		return true
	default:
		return false
	}
}

// Spend commitments for a rate card. The customer is committed to spend at least
// the minimum amount and at most the maximum amount.
type SpendCommitments struct {
	// The customer is committed to spend at least the amount.
	MinimumAmount *Numeric `json:"minimum_amount,omitempty"`
	// The customer is limited to spend at most the amount.
	MaximumAmount *Numeric `json:"maximum_amount,omitempty"`
}

// Subscription reference represents a reference to the specific subscription item
// this entity represents.
type SubscriptionReference struct {
	// The ID of the subscription.
	ID string `json:"id"`
	// The phase of the subscription.
	Phase SubscriptionReferencePhase `json:"phase"`
}

type SubscriptionReferencePhase struct {
	// The ID of the phase.
	ID string `json:"id"`
	// The item of the phase.
	Item SubscriptionReferencePhaseItem `json:"item"`
}

type SubscriptionReferencePhaseItem struct {
	// The ID of the item.
	ID string `json:"id"`
}

// Tax behavior.
//
// This enum is used to specify whether tax is included in the price or excluded
// from the price.
type TaxBehavior string

const (
	TaxBehaviorInclusive TaxBehavior = "inclusive"
	TaxBehaviorExclusive TaxBehavior = "exclusive"
)

func (value TaxBehavior) Valid() bool {
	switch value {
	case TaxBehaviorInclusive, TaxBehaviorExclusive:
		return true
	default:
		return false
	}
}

// TaxCode reference.
type TaxCodeReference struct {
	ID string `json:"id"`
}

// Set of provider specific tax configs.
type TaxConfig struct {
	// Tax behavior.
	//
	// If not specified the billing profile is used to determine the tax behavior. If
	// not specified in the billing profile, the provider's default behavior is used.
	Behavior *TaxBehavior `json:"behavior,omitempty"`
	// Stripe tax config.
	Stripe *TaxConfigStripe `json:"stripe,omitempty"`
	// External invoicing tax config.
	ExternalInvoicing *TaxConfigExternalInvoicing `json:"external_invoicing,omitempty"`
	// Tax code ID.
	TaxCodeID *string `json:"tax_code_id,omitempty"`
	// Tax code reference.
	//
	// When both `tax_code` and `tax_code_id` are provided, `tax_code` takes
	// precedence. When `stripe.code` is also provided, `tax_code` still wins and
	// `stripe.code` is ignored.
	TaxCode *TaxCodeReference `json:"tax_code,omitempty"`
}

// External invoicing tax config.
type TaxConfigExternalInvoicing struct {
	// The tax code should be interpreted by the external invoicing provider.
	Code string `json:"code"`
}

// The tax config for Stripe.
type TaxConfigStripe struct {
	// Product [tax code](https://docs.stripe.com/tax/tax-codes).
	Code string `json:"code"`
}

// Totals contains the summaries of all calculations for a billing resource.
type Totals struct {
	// The total value of the resource before taxes, discounts and commitments.
	Amount Numeric `json:"amount"`
	// The total tax amount applied to the resource.
	TaxesTotal Numeric `json:"taxes_total"`
	// The total tax amount already included in the resource amount.
	TaxesInclusiveTotal Numeric `json:"taxes_inclusive_total"`
	// The total tax amount added on top of the resource amount.
	TaxesExclusiveTotal Numeric `json:"taxes_exclusive_total"`
	// The total amount contributed by additional charges.
	ChargesTotal Numeric `json:"charges_total"`
	// The total amount deducted through discounts.
	DiscountsTotal Numeric `json:"discounts_total"`
	// The total amount deducted through credits before taxes are applied.
	CreditsTotal Numeric `json:"credits_total"`
	// The final total value of the resource after taxes, discounts and commitments.
	Total Numeric `json:"total"`
}

// Unit conversion configuration.
//
// Transforms raw metered quantities into billing-ready units before pricing and
// entitlement evaluation. Applied at the rate card level so the same feature can
// be billed in different units across plans.
//
// Examples:
//
// - Meter bytes, bill GB: operation=divide, conversionFactor=1e9,
// rounding=ceiling, displayUnit="GB"
// - Meter seconds, bill hours: operation=divide, conversionFactor=3600,
// rounding=ceiling, displayUnit="hours"
// - Cost + 20% margin: operation=multiply, conversionFactor=1.2
// - Bill per million tokens: operation=divide, conversionFactor=1e6,
// rounding=ceiling, displayUnit="M"
//
// v1 equivalents:
//
// - DynamicPrice(multiplier): operation=multiply, conversionFactor=multiplier +
// UnitPrice(amount=1)
// - PackagePrice(amount, quantityPerPkg): operation=divide,
// conversionFactor=quantityPerPkg, rounding=ceiling + UnitPrice(amount)
type UnitConfig struct {
	// The arithmetic operation to apply to the raw metered quantity.
	Operation UnitConfigOperation `json:"operation"`
	// The factor used in the conversion operation.
	//
	// - For `divide`: `converted = raw / conversionFactor`.
	// - For `multiply`: `converted = raw × conversionFactor`.
	//
	// Must be a positive non-zero value.
	ConversionFactor Numeric `json:"conversion_factor"`
	// The rounding mode applied to the converted quantity for invoicing.
	//
	// Defaults to none (no rounding). Entitlement checks always use the precise
	// (unrounded) value.
	Rounding *UnitConfigRoundingMode `json:"rounding,omitempty"`
	// The number of decimal places to retain after rounding.
	//
	// Only meaningful when rounding is not "none". Defaults to 0 (round to whole
	// numbers).
	Precision *int64 `json:"precision,omitempty"`
	// A human-readable label for the converted unit shown on invoices and in the
	// customer portal (e.g., "GB", "hours", "M tokens").
	//
	// Optional. When omitted, no unit label is rendered.
	DisplayUnit *string `json:"display_unit,omitempty"`
}

// The arithmetic operation used to convert raw metered units into billing units.
//
// - `divide`: Divide the metered quantity by the conversion factor (e.g., bytes ÷
// 1e9 = GB).
// - `multiply`: Multiply the metered quantity by the conversion factor (e.g., cost
// × 1.2 = cost + 20% margin).
type UnitConfigOperation string

const (
	UnitConfigOperationDivide   UnitConfigOperation = "divide"
	UnitConfigOperationMultiply UnitConfigOperation = "multiply"
)

func (value UnitConfigOperation) Valid() bool {
	switch value {
	case UnitConfigOperationDivide, UnitConfigOperationMultiply:
		return true
	default:
		return false
	}
}

// The rounding mode applied to the converted quantity for invoicing.
//
// Rounding is applied only to the invoiced quantity. Entitlement balance checks
// use the precise decimal value after conversion.
//
// - `ceiling`: Round up to the next integer (typical for package-style billing).
// - `floor`: Round down to the previous integer.
// - `half_up`: Round to the nearest integer, with 0.5 rounding up.
// - `none`: No rounding; the converted value is used as-is.
type UnitConfigRoundingMode string

const (
	UnitConfigRoundingModeCeiling UnitConfigRoundingMode = "ceiling"
	UnitConfigRoundingModeFloor   UnitConfigRoundingMode = "floor"
	UnitConfigRoundingModeHalfUp  UnitConfigRoundingMode = "half_up"
	UnitConfigRoundingModeNone    UnitConfigRoundingMode = "none"
)

func (value UnitConfigRoundingMode) Valid() bool {
	switch value {
	case UnitConfigRoundingModeCeiling, UnitConfigRoundingModeFloor, UnitConfigRoundingModeHalfUp, UnitConfigRoundingModeNone:
		return true
	default:
		return false
	}
}

// Payment settings for a billing workflow when the collection method is charge
// automatically.
type WorkflowPaymentChargeAutomaticallySettings struct {
	// The collection method for the invoice.
	CollectionMethod CollectionMethod `json:"collection_method"`
}

// Payment settings for a billing workflow when the collection method is send
// invoice.
type WorkflowPaymentSendInvoiceSettings struct {
	// The collection method for the invoice.
	CollectionMethod CollectionMethod `json:"collection_method"`
	// The period after which the invoice is due. With some payment solutions it's only
	// applicable for manual collection method.
	DueAfter *string `json:"due_after,omitempty"`
}

// Payment settings for a billing workflow.
//
// WorkflowPaymentSettings is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the WorkflowPaymentSettingsFrom* constructors.
// The exported CollectionMethod field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.
type WorkflowPaymentSettings struct {
	CollectionMethod string `json:"collection_method"`
	raw              json.RawMessage
}

func (u *WorkflowPaymentSettings) UnmarshalJSON(data []byte) error {
	u.raw = append([]byte(nil), data...)
	if string(data) == "null" {
		u.CollectionMethod = ""
		return nil
	}

	var envelope struct {
		Value string `json:"collection_method"`
	}
	if err := json.Unmarshal(data, &envelope); err != nil {
		return err
	}
	u.CollectionMethod = envelope.Value
	return nil
}

func (u WorkflowPaymentSettings) MarshalJSON() ([]byte, error) {
	if len(u.raw) == 0 {
		return []byte("null"), nil
	}
	return append([]byte(nil), u.raw...), nil
}

func (u WorkflowPaymentSettings) AsWorkflowPaymentChargeAutomaticallySettings() (*WorkflowPaymentChargeAutomaticallySettings, error) {
	if u.CollectionMethod != "charge_automatically" {
		return nil, fmt.Errorf("WorkflowPaymentSettings: expected collection_method %q, got %q", "charge_automatically", u.CollectionMethod)
	}
	var value WorkflowPaymentChargeAutomaticallySettings
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func WorkflowPaymentSettingsFromWorkflowPaymentChargeAutomaticallySettings(value WorkflowPaymentChargeAutomaticallySettings) (WorkflowPaymentSettings, error) {
	value.CollectionMethod = "charge_automatically"
	raw, err := json.Marshal(value)
	if err != nil {
		return WorkflowPaymentSettings{}, err
	}
	var result WorkflowPaymentSettings
	if err := result.UnmarshalJSON(raw); err != nil {
		return WorkflowPaymentSettings{}, err
	}
	return result, nil
}

func (u WorkflowPaymentSettings) AsWorkflowPaymentSendInvoiceSettings() (*WorkflowPaymentSendInvoiceSettings, error) {
	if u.CollectionMethod != "send_invoice" {
		return nil, fmt.Errorf("WorkflowPaymentSettings: expected collection_method %q, got %q", "send_invoice", u.CollectionMethod)
	}
	var value WorkflowPaymentSendInvoiceSettings
	if err := json.Unmarshal(u.raw, &value); err != nil {
		return nil, err
	}
	return &value, nil
}

func WorkflowPaymentSettingsFromWorkflowPaymentSendInvoiceSettings(value WorkflowPaymentSendInvoiceSettings) (WorkflowPaymentSettings, error) {
	value.CollectionMethod = "send_invoice"
	raw, err := json.Marshal(value)
	if err != nil {
		return WorkflowPaymentSettings{}, err
	}
	var result WorkflowPaymentSettings
	if err := result.UnmarshalJSON(raw); err != nil {
		return WorkflowPaymentSettings{}, err
	}
	return result, nil
}