unitep

type BulkUpsertUnitsEndpoint struct{}

type BulkUpsertUnitsRequest struct {
	// Units to create or update, matched by name or abbreviation within the account.
	Units []UpsertUnitInput `json:"units" validate:"required,min=1,max=1000,dive"`
}

type CreateUnitEndpoint struct{}

type CreateUnitRequest struct {
	// Display name of the unit (e.g. "Gram").
	//
	// Must be unique within the account.
	Name string `json:"name" validate:"required,max=255"`
	// Short abbreviation for the unit (e.g. "g").
	//
	// Must be unique within the account.
	Abbreviation string `json:"abbreviation" validate:"required"`
	// The dimension this unit measures, such as mass, volume, or currency.
	//
	// Units can only be converted to other units of the same dimension, and the dimension cannot be changed after the unit is created.
	Type constants.UnitType `json:"type" validate:"required"`
	// Numerator of the ratio that converts a quantity in this unit into the dimension's base unit.
	//
	// A quantity is converted with `value × (ratio_numerator / ratio_denominator) + (offset_numerator / offset_denominator)`, so a kilogram in a gram-based dimension has a numerator of `1000` and a denominator of `1`.
	RatioNumerator string `json:"ratio_numerator" validate:"required,decimal" format:"decimal"`
	// Denominator of the ratio that converts a quantity in this unit into the dimension's base unit.
	//
	// Must not be zero.
	RatioDenominator string `json:"ratio_denominator" validate:"required,nonzero_decimal" format:"decimal"`
	// Numerator of the conversion offset, applied after the ratio for scales that do not share a zero point, such as temperature.
	//
	// Send `0` for units that convert by ratio alone.
	OffsetNumerator string `json:"offset_numerator" validate:"required,decimal" format:"decimal"`
	// Denominator of the conversion offset.
	//
	// Must not be zero, so send `1` when the unit has no offset.
	OffsetDenominator string `json:"offset_denominator" validate:"required,nonzero_decimal" format:"decimal"`
}

type DeleteUnitEndpoint struct{}

type DeleteUnitRequest struct {
	// Unit ID.
	UnitID string `path:"id" validate:"required"`
}

type ExportUnitsEndpoint struct{}

type ExportUnitsRequest struct {
	// Free-text search term matched against unit names.
	Query *string `json:"q"`
}

type ListUnitsEndpoint struct{}

type ListUnitsRequest struct {
	apiresource.PaginationRequest
	// Filter by unit dimension.
	Type *constants.UnitType `query:"type"`
	// Return only units that belong to at least one of the given unit groups.
	UnitGroupIDs []string `query:"unit_group_ids"`
}

type RetrieveUnitEndpoint struct{}

type RetrieveUnitRequest struct {
	// Unit ID.
	UnitID string `path:"id" validate:"required"`
}

type UnitSvc interface {
	ListUnits(ctx context.Context, req *ListUnitsRequest) (*apiresource.List[apiresource.Unit], *apierror.APIError)
	ExportUnits(ctx context.Context, req *ExportUnitsRequest) (*apiresource.Job, *apierror.APIError)
	GetUnit(ctx context.Context, req *RetrieveUnitRequest) (*apiresource.Unit, *apierror.APIError)
	CreateUnit(ctx context.Context, req *CreateUnitRequest) (*apiresource.Unit, *apierror.APIError)
	UpdateUnit(ctx context.Context, req *UpdateUnitRequest) (*apiresource.Unit, *apierror.APIError)
	BulkUpsertUnits(ctx context.Context, req *BulkUpsertUnitsRequest) (*apiresource.Job, *apierror.APIError)
	DeleteUnit(ctx context.Context, req *DeleteUnitRequest) (*apiresource.EmptyResource, *apierror.APIError)
	ValidateUnits(ctx context.Context, req *ValidateUnitsRequest) (*apiresource.ValidateUnitsResponse, *apierror.APIError)
}

type UnitSvcConfig struct {
	// CoreClient (required) is the core-service gRPC client.
	CoreClient pb.CoreServiceClient
}

type UpdateUnitEndpoint struct{}

type UpdateUnitRequest struct {
	// Unit ID.
	UnitID string `path:"id" validate:"required"`
	// Display name of the unit.
	//
	// Must be unique within the account.
	Name field.Optional[string] `json:"name,omitzero" validate:"omitempty,max=255"`
	// Short abbreviation for the unit.
	//
	// Must be unique within the account.
	Abbreviation field.Optional[string] `json:"abbreviation,omitzero" validate:"omitempty"`
	// Numerator of the ratio that converts a quantity in this unit into the dimension's base unit.
	//
	// A quantity is converted with `value × (ratio_numerator / ratio_denominator) + (offset_numerator / offset_denominator)`.
	RatioNumerator field.Optional[string] `json:"ratio_numerator,omitzero" validate:"omitempty,decimal" format:"decimal"`
	// Denominator of the ratio that converts a quantity in this unit into the dimension's base unit.
	//
	// Must not be zero.
	RatioDenominator field.Optional[string] `json:"ratio_denominator,omitzero" validate:"omitempty,nonzero_decimal" format:"decimal"`
	// Numerator of the conversion offset, applied after the ratio for scales that do not share a zero point, such as temperature.
	OffsetNumerator field.Optional[string] `json:"offset_numerator,omitzero" validate:"omitempty,decimal" format:"decimal"`
	// Denominator of the conversion offset.
	//
	// Must not be zero.
	OffsetDenominator field.Optional[string] `json:"offset_denominator,omitzero" validate:"omitempty,nonzero_decimal" format:"decimal"`
}

type UpsertUnitInput struct {
	// Display name of the unit (e.g. "Gram"). A row matching a system unit fails — system
	// units cannot be modified.
	Name string `json:"name" validate:"required,max=255"`
	// Short abbreviation for the unit (e.g. "g"). Also used for matching — see `name`.
	Abbreviation string `json:"abbreviation" validate:"required,max=191"`
	// Unit dimension code. Create-only — a row that changes an existing unit's dimension fails.
	Type constants.UnitType `json:"type" validate:"required"`
	// Conversion ratio numerator relative to the base unit, as a decimal string.
	RatioNumerator string `json:"ratio_numerator" validate:"required" format:"decimal"`
	// Conversion ratio denominator relative to the base unit, as a decimal string.
	RatioDenominator string `json:"ratio_denominator" validate:"required" format:"decimal"`
	// Conversion offset numerator, as a decimal string.
	OffsetNumerator string `json:"offset_numerator" validate:"required" format:"decimal"`
	// Conversion offset denominator, as a decimal string.
	OffsetDenominator string `json:"offset_denominator" validate:"required" format:"decimal"`
	// Whether the unit is its dimension's base unit. Bulk upsert never creates a base unit
	// and rejects a change to an existing one.
	IsBaseUnit bool `json:"is_base_unit"`
}

type ValidateUnitsEndpoint struct{}

type ValidateUnitsRequest struct {
	// Abbreviations to look up, keyed by any identifier you choose.
	//
	// The keys are echoed back on the matching units, so a spreadsheet import can use row numbers or column names to trace each abbreviation back to its source.
	UnitMap map[string]string `json:"unit_map" validate:"required"`
}