productep

type BulkUpsertProductsEndpoint struct{}

type BulkUpsertProductsRequest struct {
	// Products to create or update, matched by SKU within the account.
	Products []UpsertProductInput `json:"products" validate:"required,min=1,max=1000,dive"`
}

type ChangeProductProductLineEndpoint struct{}

type ChangeProductProductLineRequest struct {
	// Product ID.
	ProductID string `path:"id" validate:"required"`
	// ID of the product line to assign to the product.
	ProductLineID string `path:"product_line_id" validate:"required"`
}

type CreateProductEndpoint struct{}

type CreateProductRequest struct {
	// Stock keeping unit code for the product's item.
	//
	// Must be unique within the account; creation fails with a conflict error if another item already uses it.
	SKU string `json:"sku" validate:"required,max=255"`
	// Free-form description of the product.
	Description field.Optional[string] `json:"description,omitzero"`
	// Free-form notes about the product.
	Notes field.Optional[string] `json:"notes,omitzero"`
	// Product type code, which determines how the product behaves on orders and invoices.
	//
	// - `sale`: a standard sellable product.
	// - `service`: a non-physical service line, such as labor or installation.
	// - `shipping`: a shipping charge applied to an order.
	// - `credit`: a credit applied against an order or invoice.
	// - `return`: a returned product (RMA).
	// - `tax`: a tax line.
	ProductTypeCode constants.ProductTypeCode `json:"type" validate:"required"`
	// ID of the product line to assign the product to.
	//
	// The product line must be one your account owns or a shared system line; anything else fails as not found. Buyers are granted access to whole product lines, so a product created without one never appears in the customer portal, whatever its `portal_visibility`.
	ProductLineID field.Optional[string] `json:"product_line_id,omitzero" validate:"omitempty"`
	// ID of the item category for the product's item.
	//
	// The category's unit group determines the default units used for the product's pricing rates and inventory tracking.
	CategoryID string `json:"category_id" validate:"required"`
	// Whether the product is shown to buyers in the customer portal.
	//
	// - `visible`: buyers can see and order the product in the portal.
	// - `hidden`: the product is concealed from the portal but remains usable internally.
	//
	// When omitted, the product is created hidden, so it must be set to `visible` before buyers can see it.
	PortalVisibility field.Optional[constants.CustomerPortalVisibility] `json:"portal_visibility,omitzero" default:"hidden"`
	// Initial selling price per unit.
	//
	// When set, the numerator unit must be a currency unit and the denominator unit must not be. When omitted, the price is initialized to a zero rate in the category's base unit.
	UnitPrice field.Optional[apirequest.RateInput] `json:"unit_price,omitzero"`
	// Initial cost per unit.
	//
	// The same unit rule as `unit_price` applies: the numerator unit must be a currency unit and the denominator unit must not be. 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"`
	// Attribute IDs to link to the product's item at creation time.
	//
	// Every ID must already exist in your account, and each attribute's property must be one the item's category carries; an ID that fails either check fails the whole request rather than being skipped.
	AttributeIDs []string `json:"attribute_ids,omitzero"`
}

type DeleteProductEndpoint struct{}

type DeleteProductRequest struct {
	// Product ID.
	ProductID string `path:"id" validate:"required"`
}

type ExportProductsEndpoint struct{}

type ExportProductsRequest struct {
	// Free-text search matched against the SKU and description of each product's item.
	Query *string `json:"q"`
	// Filter by the item category the product's item belongs to.
	CategoryIDs []string `json:"category_ids"`
	// Filter to products whose item carries at least one of these attributes.
	AttributeIDs []string `json:"attribute_ids"`
	// Filter by product line IDs.
	//
	// Combined with `customer_ids`, products matching either filter are exported.
	ProductLineIDs []string `json:"product_line_ids"`
	// Restrict the export to products these customer accounts are entitled to buy.
	//
	// A product matches when its product line has been granted to the customer directly, through the customer's account group, or through the account group used for the customer's pricing.
	CustomerIDs []string `json:"customer_ids"`
	// Start of creation date range.
	StartDate *time.Time `json:"starts_at"`
	// End of creation date range.
	EndDate *time.Time `json:"ends_at"`
}

type ListProductsEndpoint struct{}

type ListProductsRequest struct {
	apiresource.PaginationRequest
	// Restrict results to products these customer accounts are entitled to buy.
	//
	// A product matches when its product line has been granted to the customer directly, through the customer's account group, or through the account group used for the customer's pricing. Combined with `product_line_ids` this widens the results rather than narrowing them: products matching either filter are returned.
	CustomerIDs []string `query:"customer_ids"`
	// Filter by product line IDs.
	//
	// Combined with `customer_ids`, products matching either filter are returned.
	ProductLineIDs []string `query:"product_line_ids"`
	// Filter by the item category the product's item belongs to.
	CategoryIDs []string `query:"category_ids"`
	// Filter to products whose item carries at least one of these attributes.
	AttributeIDs []string `query:"attribute_ids"`
	// Start of creation date range.
	StartDate *time.Time `query:"starts_at"`
	// End of creation date range.
	EndDate *time.Time `query:"ends_at"`
	// Filter by customer portal visibility.
	PortalVisibility *constants.CustomerPortalVisibility `query:"portal_visibility"`
}

type ProductSvc interface {
	ListProducts(ctx context.Context, req *ListProductsRequest) (*apiresource.List[apiresource.Product], *apierror.APIError)
	GetProduct(ctx context.Context, req *RetrieveProductRequest) (*apiresource.Product, *apierror.APIError)
	CreateProduct(ctx context.Context, req *CreateProductRequest) (*apiresource.Product, *apierror.APIError)
	BulkUpsertProducts(ctx context.Context, req *BulkUpsertProductsRequest) (*apiresource.Job, *apierror.APIError)
	UpdateProduct(ctx context.Context, req *UpdateProductRequest) (*apiresource.Product, *apierror.APIError)
	DeleteProduct(ctx context.Context, req *DeleteProductRequest) (*apiresource.Product, *apierror.APIError)
	ChangeProductProductLine(ctx context.Context, req *ChangeProductProductLineRequest) (*apiresource.Product, *apierror.APIError)
	ValidateProducts(ctx context.Context, req *ValidateProductsRequest) (*apiresource.ValidateProductsResponse, *apierror.APIError)
	ExportProducts(ctx context.Context, req *ExportProductsRequest) (*apiresource.Job, *apierror.APIError)
}

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

type RetrieveProductEndpoint struct{}

type RetrieveProductRequest struct {
	// Product ID.
	ProductID string `path:"id" validate:"required"`
}

type UpdateProductEndpoint struct{}

type UpdateProductRequest struct {
	// Product ID.
	ProductID string `path:"id" validate:"required"`
	// New stock keeping unit code for the product's item.
	//
	// Must be unique within the account; the update fails with a conflict error if another item already uses it.
	SKU field.Optional[string] `json:"sku,omitzero" validate:"omitempty,max=255"`
	// Free-form description of the product.
	//
	// Send `null` to clear.
	Description field.Clearable[string] `json:"description,omitzero"`
	// Free-form notes about the product.
	//
	// Send `null` to clear.
	Notes field.Clearable[string] `json:"notes,omitzero"`
	// Whether the product is shown to buyers in the customer portal.
	//
	// - `visible`: buyers can see and order the product in the portal.
	// - `hidden`: the product is concealed from the portal but remains usable internally.
	PortalVisibility field.Optional[constants.CustomerPortalVisibility] `json:"portal_visibility,omitzero"`
	// New selling price per unit.
	//
	// The numerator unit must be a currency unit and the denominator unit must not be. The new rate replaces the price on the product's backing item.
	UnitPrice field.Optional[apirequest.RateInput] `json:"unit_price,omitzero"`
}

type UpsertProductInput struct {
	// SKU for the product, used to match an existing product within the account. If it
	// exists the product is updated in place; otherwise a new product is created. A SKU
	// already used by a non-product item fails that row.
	SKU string `json:"sku" validate:"required,max=255"`
	// Product type. Create-only; defaults to `sale` when omitted.
	Type field.Optional[constants.ProductTypeCode] `json:"type,omitzero"`
	// Product description.
	Description field.Optional[string] `json:"description,omitzero"`
	// Product notes.
	Notes field.Optional[string] `json:"notes,omitzero"`
	// Item category to place the product in, referenced by `id` or `name`. Create-only.
	Category apirequest.ObjectIdentifier `json:"category" validate:"required"`
	// Product line to assign, referenced by `id` or `name`. Create-only.
	ProductLine field.Optional[apirequest.ObjectIdentifier] `json:"product_line,omitzero"`
	// Whether the product is shown to buyers in the customer portal. Defaults to `hidden`
	// on create; preserved when omitted on update.
	PortalVisibility field.Optional[constants.CustomerPortalVisibility] `json:"portal_visibility,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 product, matched/created by name + value. Additive —
	// existing attributes are not removed.
	Properties []UpsertProductProperty `json:"properties" default:"[]" validate:"dive"`
}

type UpsertProductProperty struct {
	// Property name (e.g. "Color"). Matched case-insensitively; created if missing.
	Name string `json:"name" validate:"required,max=255"`
	// Property value (e.g. "Red"). 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"`
}

type ValidateProductsEndpoint struct{}

type ValidateProductsRequest struct {
	// Map of caller-chosen keys to SKU values to look up.
	//
	// SKUs are matched case-insensitively. Each key is echoed back in the response with its matched product; keys whose SKU does not match any product are omitted.
	ProductsMap map[string]string `json:"products_map" validate:"required"`
}