customfields.go

package vsax

import (
	"context"
	"fmt"
	"iter"
	"net/http"
	"strconv"
)

// Custom field types.
const (
	CustomFieldTypeText    = "Text"
	CustomFieldTypeNumber  = "Number"
	CustomFieldTypeDate    = "Date"
	CustomFieldTypeBoolean = "Boolean"
)

// Custom field context types.
const (
	ContextGlobal       = "Global"
	ContextOrganization = "Organization"
	ContextSite         = "Site"
	ContextGroup        = "Group"
	ContextDevice       = "Device"
	ContextScope        = "Scope"
	ContextScript       = "Script"
)

// CustomFieldDef is a custom-field definition (as distinct from CustomField,
// which is a per-entity assignment).
type CustomFieldDef struct {
	ID             int64    `json:"Id"`
	Name           string   `json:"Name,omitempty"`
	Description    string   `json:"Description,omitempty"`
	Type           string   `json:"Type,omitempty"`
	DefaultValue   string   `json:"DefaultValue,omitempty"`
	GlobalValue    string   `json:"GlobalValue,omitempty"`
	IsReadOnly     bool     `json:"IsReadOnly"`
	Contexts       []string `json:"Contexts,omitempty"`
	ExpirationDate Time     `json:"ExpirationDate,omitzero"`
	CreatedAt      Time     `json:"CreatedAt,omitzero"`
}

// CustomFieldUsageEntry records one place a custom field is used.
type CustomFieldUsageEntry struct {
	UsageContextType string `json:"UsageContextType,omitempty"`
	ContextItemID    string `json:"ContextItemId,omitempty"`
	Value            string `json:"Value,omitempty"`
}

// AssignCustomFieldRequest is the body for POST /customFields/{id}/assign.
//
// Set UseDefaultValue=true to adopt the field's default; otherwise supply a
// Value. Assigning to a (ContextType, ContextItemId) pair that already has
// the field assigned returns 400; use UpdateAssignment instead.
type AssignCustomFieldRequest struct {
	ContextType     string `json:"ContextType"`
	ContextItemID   string `json:"ContextItemId"`
	UseDefaultValue bool   `json:"UseDefaultValue,omitempty"`
	Value           string `json:"Value,omitempty"`
}

// UpdateAssignedCustomFieldRequest is the body for PUT /customFields/{id}/updateAssigned.
type UpdateAssignedCustomFieldRequest struct {
	ContextType     string `json:"ContextType"`
	ContextItemID   string `json:"ContextItemId"`
	UseDefaultValue bool   `json:"UseDefaultValue,omitempty"`
	Value           string `json:"Value,omitempty"`
}

// UnassignCustomFieldRequest is the body for POST /customFields/{id}/unassign.
type UnassignCustomFieldRequest struct {
	ContextType   string `json:"ContextType"`
	ContextItemID string `json:"ContextItemId"`
}

// CustomFieldAssignmentResult is the response to Assign/UpdateAssignment.
type CustomFieldAssignmentResult struct {
	ContextType   string `json:"ContextType,omitempty"`
	ContextItemID string `json:"ContextItemId,omitempty"`
	ID            int64  `json:"Id"`
	Name          string `json:"Name,omitempty"`
	Value         string `json:"Value,omitempty"`
	Type          string `json:"Type,omitempty"`
}

// CustomFieldService provides access to custom-field endpoints under /customFields.
type CustomFieldService struct {
	client *Client
	list   listService[CustomFieldDef]
}

func newCustomFieldService(c *Client) *CustomFieldService {
	return &CustomFieldService{client: c, list: listService[CustomFieldDef]{client: c, path: "/customFields"}}
}

// List retrieves one page of custom-field definitions.
func (s *CustomFieldService) List(ctx context.Context, q *Query) (*PagedResult[CustomFieldDef], error) {
	return s.list.List(ctx, q)
}

// All iterates all custom-field definitions across pages.
func (s *CustomFieldService) All(ctx context.Context, q *Query) iter.Seq2[CustomFieldDef, error] {
	return s.list.All(ctx, q)
}

// Get retrieves one custom-field definition by ID.
func (s *CustomFieldService) Get(ctx context.Context, id int64) (*CustomFieldDef, error) {
	env, err := s.client.do(ctx, http.MethodGet, "/customFields/"+strconv.FormatInt(id, 10), nil)
	if err != nil {
		return nil, err
	}
	return decodeOne[CustomFieldDef](env)
}

// Usage lists where a custom field is currently assigned.
func (s *CustomFieldService) Usage(ctx context.Context, id int64, q *Query) (*PagedResult[CustomFieldUsageEntry], error) {
	return listSub[CustomFieldUsageEntry](ctx, s.client, "/customFields/"+strconv.FormatInt(id, 10)+"/usage", q)
}

// AllUsage iterates all usage entries for a custom field across pages.
func (s *CustomFieldService) AllUsage(ctx context.Context, id int64, q *Query) iter.Seq2[CustomFieldUsageEntry, error] {
	return allFromList(ctx, func() (*PagedResult[CustomFieldUsageEntry], error) {
		return s.Usage(ctx, id, q)
	})
}

// Assign assigns the custom field to an entity. Returns 400 if already assigned.
func (s *CustomFieldService) Assign(ctx context.Context, id int64, body *AssignCustomFieldRequest) (*CustomFieldAssignmentResult, error) {
	if body == nil || body.ContextType == "" || body.ContextItemID == "" {
		return nil, fmt.Errorf("vsax: ContextType and ContextItemId are required")
	}
	env, err := s.client.do(ctx, http.MethodPost, "/customFields/"+strconv.FormatInt(id, 10)+"/assign", body)
	if err != nil {
		return nil, err
	}
	return decodeOne[CustomFieldAssignmentResult](env)
}

// UpdateAssignment updates the value of an existing custom-field assignment.
func (s *CustomFieldService) UpdateAssignment(ctx context.Context, id int64, body *UpdateAssignedCustomFieldRequest) (*CustomFieldAssignmentResult, error) {
	if body == nil || body.ContextType == "" || body.ContextItemID == "" {
		return nil, fmt.Errorf("vsax: ContextType and ContextItemId are required")
	}
	env, err := s.client.do(ctx, http.MethodPut, "/customFields/"+strconv.FormatInt(id, 10)+"/updateAssigned", body)
	if err != nil {
		return nil, err
	}
	return decodeOne[CustomFieldAssignmentResult](env)
}

// Unassign removes a custom field from an entity.
func (s *CustomFieldService) Unassign(ctx context.Context, id int64, body *UnassignCustomFieldRequest) error {
	if body == nil || body.ContextType == "" || body.ContextItemID == "" {
		return fmt.Errorf("vsax: ContextType and ContextItemId are required")
	}
	_, err := s.client.do(ctx, http.MethodPost, "/customFields/"+strconv.FormatInt(id, 10)+"/unassign", body)
	return err
}