materialep

type BulkUpsertMaterialsEndpoint struct{}

type BulkUpsertMaterialsRequest struct {
	// Materials to create or update, matched by SKU within the account.
	Materials []UpsertMaterialInput `json:"materials" validate:"required,min=1,max=1000,dive"`
}

type CreateMaterialEndpoint struct{}

type CreateMaterialRequest struct {
	// Stock keeping unit code for the material.
	//
	// Must be unique within the account; creating a material with a SKU already used by another item fails with a conflict error.
	SKU string `json:"sku" validate:"required,max=255"`
	// Free-form description of the material.
	Description field.Optional[string] `json:"description,omitzero"`
	// Free-form notes about the material.
	Notes field.Optional[string] `json:"notes,omitzero"`
	// ID of the item category to place the material in.
	//
	// The category's unit group determines the base unit used for the material's rates (`unit_value`, `unit_cost`, `burn_rate`).
	CategoryID string `json:"category_id" validate:"required"`
	// Reorder threshold: when on-hand stock falls to this quantity, the material should be reordered.
	//
	// When omitted, the material is created without a reorder threshold.
	OrderPoint field.Optional[QuantityInputRequest] `json:"order_point,omitzero"`
	// Expected time between placing an order for this material and receiving it, expressed as a quantity in a time unit (e.g. days).
	//
	// When omitted, the material is created without a lead time.
	LeadTime field.Optional[QuantityInputRequest] `json:"lead_time,omitzero"`
	// Initial selling price per unit.
	//
	// `numerator_unit_id` must reference a currency unit and `denominator_unit_id` must reference a non-currency unit (e.g. `$5` per `ea`). When omitted, the price is initialized to a zero rate in the category's base unit. It becomes the `unit_value` rate on the material's item; the material update endpoint cannot change it afterwards.
	UnitPrice field.Optional[apirequest.RateInput] `json:"unit_price,omitzero"`
	// Initial cost per unit.
	//
	// Follows the same unit rule as `unit_price`: currency numerator, non-currency denominator. When omitted, the cost is initialized to a zero rate in the category's base unit.
	UnitCost field.Optional[apirequest.RateInput] `json:"unit_cost,omitzero"`
	// IDs of existing attributes to link to the material at creation time.
	//
	// Each attribute's property must be one the material's category carries; an attribute from any other property fails the whole request.
	AttributeIDs []string `json:"attribute_ids,omitzero"`
}

type DeleteMaterialEndpoint struct{}

type DeleteMaterialRequest struct {
	// ID of the material to delete.
	ItemID string `path:"id" validate:"required"`
}

type ExportMaterialsEndpoint struct{}

type ExportMaterialsRequest struct {
	// Free-text search term matched against material SKU and description.
	Query *string `json:"q"`
	// Filter to materials in any of these categories.
	CategoryIDs []string `json:"category_ids"`
	// Filter to materials carrying any of these attributes.
	AttributeIDs []string `json:"attribute_ids"`
	// Filter to materials created on or after this date.
	StartDate *time.Time `json:"starts_at"`
	// Filter to materials created on or before this date.
	EndDate *time.Time `json:"ends_at"`
}

type ListMaterialsEndpoint struct{}

type ListMaterialsRequest struct {
	apiresource.PaginationRequest
	// Filter to materials in any of these categories.
	CategoryIDs []string `query:"category_ids"`
	// Filter to materials carrying any of these attributes.
	AttributeIDs []string `query:"attribute_ids"`
	// Filter to materials created on or after this date.
	StartDate *time.Time `query:"starts_at"`
	// Filter to materials created on or before this date.
	EndDate *time.Time `query:"ends_at"`
}

type MaterialSvc interface {
	ListMaterials(ctx context.Context, req *ListMaterialsRequest) (*apiresource.List[apiresource.Material], *apierror.APIError)
	GetMaterial(ctx context.Context, req *RetrieveMaterialRequest) (*apiresource.Material, *apierror.APIError)
	CreateMaterial(ctx context.Context, req *CreateMaterialRequest) (*apiresource.Material, *apierror.APIError)
	BulkUpsertMaterials(ctx context.Context, req *BulkUpsertMaterialsRequest) (*apiresource.Job, *apierror.APIError)
	UpdateMaterial(ctx context.Context, req *UpdateMaterialRequest) (*apiresource.Material, *apierror.APIError)
	DeleteMaterial(ctx context.Context, req *DeleteMaterialRequest) (*apiresource.Material, *apierror.APIError)
	ExportMaterials(ctx context.Context, req *ExportMaterialsRequest) (*apiresource.Job, *apierror.APIError)
}

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

type QuantityInputRequest struct {
	// Decimal value of the quantity.
	Value string `json:"value" validate:"required" format:"decimal"`
	// ID of the unit the value is expressed in.
	UnitID string `json:"unit_id" validate:"required"`
}

type RetrieveMaterialEndpoint struct{}

type RetrieveMaterialRequest struct {
	// ID of the material to retrieve.
	ItemID string `path:"id" validate:"required"`
}

type UpdateMaterialEndpoint struct{}

type UpdateMaterialRequest struct {
	// ID of the material to update.
	ItemID string `path:"id" validate:"required"`
	// New stock keeping unit code for the material.
	//
	// Must remain unique within the account; a conflict error is returned if another item already uses it.
	SKU field.Optional[string] `json:"sku,omitzero" validate:"omitempty,max=255"`
	// New description for the material.
	Description field.Optional[string] `json:"description,omitzero"`
	// New notes for the material.
	Notes field.Optional[string] `json:"notes,omitzero"`
	// New reorder threshold: when on-hand stock falls to this quantity, the material should be reordered.
	OrderPoint field.Optional[QuantityInputRequest] `json:"order_point,omitzero"`
	// New expected time between placing an order for this material and receiving it.
	LeadTime field.Optional[QuantityInputRequest] `json:"lead_time,omitzero"`
	// New cost per unit.
	//
	// Follows the same unit rule as on create: `numerator_unit_id` must reference a currency unit and `denominator_unit_id` must reference a non-currency unit.
	UnitCost field.Optional[apirequest.RateInput] `json:"unit_cost,omitzero"`
}

type UpsertMaterialInput struct {
	// SKU for the material, used to match an existing material within the account. If it
	// exists the material is updated in place; otherwise a new material is created. A SKU
	// already used by a non-material item fails that row.
	SKU string `json:"sku" validate:"required,max=255"`
	// Material description.
	Description field.Optional[string] `json:"description,omitzero"`
	// Material notes.
	Notes field.Optional[string] `json:"notes,omitzero"`
	// Item category to place the material in, referenced by `id` or `name`. Create-only.
	Category apirequest.ObjectIdentifier `json:"category" validate:"required"`
	// Reorder threshold quantity. When omitted on create it defaults to a zero quantity in
	// the category's base unit.
	OrderPoint field.Optional[QuantityInputRequest] `json:"order_point,omitzero"`
	// Expected lead time quantity. When omitted on create it defaults to a zero quantity in
	// the category's base unit.
	LeadTime field.Optional[QuantityInputRequest] `json:"lead_time,omitzero"`
	// Selling price per unit. Numerator must be a currency unit, denominator the per-unit
	// basis. Defaults to a zero rate in the category's base unit on create; unchanged when
	// omitted on update.
	UnitPrice field.Optional[apirequest.RateInput] `json:"unit_price,omitzero"`
	// Cost per unit. Same currency-vs-non-currency rule as `unit_price`.
	UnitCost field.Optional[apirequest.RateInput] `json:"unit_cost,omitzero"`
	// Properties to attach to the material, matched/created by name + value. Additive —
	// existing attributes are not removed.
	Properties []UpsertMaterialProperty `json:"properties" default:"[]" validate:"dive"`
}

type UpsertMaterialProperty struct {
	// Property name (e.g. "Grade"). Matched case-insensitively; created if missing.
	Name string `json:"name" validate:"required,max=255"`
	// Property value (e.g. "A36"). Matched case-insensitively; created under the property
	// if missing. A value already in use under a different property fails the whole job.
	Value string `json:"value" validate:"required,max=255"`
}