scripts.go

package vsax

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

// Script platforms.
const (
	PlatformWindows = "Windows"
	PlatformMacOS   = "Mac OS"
	PlatformLinux   = "Linux"
)

// Script execution states.
const (
	ScriptStateRunning    = "Running"
	ScriptStateSuccessful = "Successful"
	ScriptStateFailed     = "Failed"
	ScriptStateStopped    = "Stopped"
)

// Script is the list-view record for an automation script.
type Script struct {
	ID           string   `json:"Id"`
	Name         string   `json:"Name,omitempty"`
	Description  string   `json:"Description,omitempty"`
	CategoryID   int64    `json:"CategoryId,omitempty"`
	CategoryName string   `json:"CategoryName,omitempty"`
	Platforms    []string `json:"Platforms,omitempty"`
	CreatedBy    string   `json:"CreatedBy,omitempty"`
	IsBuiltIn    bool     `json:"IsBuiltIn"`
	FolderPath   string   `json:"FolderPath,omitempty"`
}

// ScriptDetails extends Script with variables and platform-specific code.
type ScriptDetails struct {
	Script
	InputVariables  []ScriptVariableDef `json:"InputVariables,omitempty"`
	OutputVariables []ScriptVariableDef `json:"OutputVariables,omitempty"`
	ScriptItems     []ScriptItem        `json:"ScriptItems,omitempty"`
}

// ScriptVariableDef is an input or output variable declared by a script.
type ScriptVariableDef struct {
	ID              int64  `json:"Id"`
	Name            string `json:"Name,omitempty"`
	CustomFieldID   *int64 `json:"CustomFieldId,omitempty"`
	CustomFieldName string `json:"CustomFieldName,omitempty"`
	VariableType    string `json:"VariableType,omitempty"` // Date | Number | Text | Boolean
	DefaultValue    string `json:"DefaultValue,omitempty"`
}

// ScriptItem is the code for one platform/language of a script.
type ScriptItem struct {
	Platform          string `json:"Platform,omitempty"`
	ScriptingLanguage string `json:"ScriptingLanguage,omitempty"` // Batch | PowerShell | Bash | VBScript
	ScriptText        string `json:"ScriptText,omitempty"`
}

// ScriptVariableOverride overrides a script input variable at run time.
type ScriptVariableOverride struct {
	ID    int64  `json:"Id"`
	Value string `json:"Value"`
}

// RunScriptRequest is the body for POST /automation/scripts/{id}/run.
//
// Per the upstream docs DeviceIdentifier is typed as a single string and the
// device must be online. Despite the plural description, the schema is
// singular; use one call per device.
type RunScriptRequest struct {
	DeviceIdentifier string                   `json:"DeviceIdentifier"`
	WebhookURL       string                   `json:"WebhookUrl,omitempty"`
	Variables        []ScriptVariableOverride `json:"Variables,omitempty"`
}

// RunScriptResult is the response to POST /automation/scripts/{id}/run.
type RunScriptResult struct {
	ExecutionID string `json:"ExecutionId"`
}

// ScriptExecution is the list-view status of a script execution.
type ScriptExecution struct {
	ID                string   `json:"Id"`
	StartTime         Time     `json:"StartTime,omitzero"`
	DurationInSeconds *float64 `json:"DurationInSeconds,omitempty"`
	State             string   `json:"State,omitempty"`
}

// ScriptExecutionDetails extends ScriptExecution with completion data.
type ScriptExecutionDetails struct {
	ScriptExecution
	EndTime         Time                   `json:"EndTime,omitzero"`
	Output          string                 `json:"Output,omitempty"`
	ExitCode        any                    `json:"ExitCode,omitempty"` // docs say string, examples show integer
	VariableOutputs []ScriptVariableOutput `json:"VariableOutputs,omitempty"`
}

// ScriptVariableOutput is one captured output variable from a script execution.
type ScriptVariableOutput struct {
	ID       int64  `json:"Id"`
	Name     string `json:"Name,omitempty"`
	Value    string `json:"Value,omitempty"`
	DataType string `json:"DataType,omitempty"`
}

// ScriptService provides access to script endpoints under /automation/scripts.
type ScriptService struct {
	client *Client
	list   listService[Script]
}

func newScriptService(c *Client) *ScriptService {
	return &ScriptService{client: c, list: listService[Script]{client: c, path: "/automation/scripts"}}
}

// List retrieves one page of scripts.
func (s *ScriptService) List(ctx context.Context, q *Query) (*PagedResult[Script], error) {
	return s.list.List(ctx, q)
}

// All iterates all scripts across pages.
func (s *ScriptService) All(ctx context.Context, q *Query) iter.Seq2[Script, error] {
	return s.list.All(ctx, q)
}

// Get retrieves a single script by ID.
func (s *ScriptService) Get(ctx context.Context, id string) (*ScriptDetails, error) {
	if id == "" {
		return nil, fmt.Errorf("vsax: script id is required")
	}
	env, err := s.client.do(ctx, http.MethodGet, "/automation/scripts/"+url.PathEscape(id), nil)
	if err != nil {
		return nil, err
	}
	return decodeOne[ScriptDetails](env)
}

// Run executes a script on one device.
func (s *ScriptService) Run(ctx context.Context, scriptID string, body *RunScriptRequest) (*RunScriptResult, error) {
	if scriptID == "" {
		return nil, fmt.Errorf("vsax: script id is required")
	}
	if body == nil || body.DeviceIdentifier == "" {
		return nil, fmt.Errorf("vsax: DeviceIdentifier is required")
	}
	env, err := s.client.do(ctx, http.MethodPost, "/automation/scripts/"+url.PathEscape(scriptID)+"/run", body)
	if err != nil {
		return nil, err
	}
	return decodeOne[RunScriptResult](env)
}

// Executions lists executions of a script on a specific device.
func (s *ScriptService) Executions(ctx context.Context, scriptID, deviceID string, q *Query) (*PagedResult[ScriptExecution], error) {
	if scriptID == "" || deviceID == "" {
		return nil, fmt.Errorf("vsax: script and device ids are required")
	}
	path := "/automation/scripts/" + url.PathEscape(scriptID) +
		"/device/" + url.PathEscape(deviceID) + "/executions"
	return listSub[ScriptExecution](ctx, s.client, path, q)
}

// AllExecutions iterates all executions of a script on a device across pages.
func (s *ScriptService) AllExecutions(ctx context.Context, scriptID, deviceID string, q *Query) iter.Seq2[ScriptExecution, error] {
	return allFromList(ctx, func() (*PagedResult[ScriptExecution], error) {
		return s.Executions(ctx, scriptID, deviceID, q)
	})
}

// Execution retrieves the details of a single script execution.
func (s *ScriptService) Execution(ctx context.Context, scriptID, deviceID, executionID string) (*ScriptExecutionDetails, error) {
	if scriptID == "" || deviceID == "" || executionID == "" {
		return nil, fmt.Errorf("vsax: script, device, and execution ids are required")
	}
	path := "/automation/scripts/" + url.PathEscape(scriptID) +
		"/device/" + url.PathEscape(deviceID) +
		"/executions/" + url.PathEscape(executionID)
	env, err := s.client.do(ctx, http.MethodGet, path, nil)
	if err != nil {
		return nil, err
	}
	return decodeOne[ScriptExecutionDetails](env)
}