client

type APIClient struct {

	// AuthToken is a JWT token for authentication (if used)
	AuthToken string

	// APIKey is the API key for authentication
	APIKey string
	// contains filtered or unexported fields
}

type Client interface {

	// AdminGetInstances retrieves all instances across all projects.
	// This is an administrative endpoint that returns all instances regardless of owner.
	// Returns a slice of Instance pointers and any error encountered.
	AdminGetInstances(ctx context.Context) ([]*models.Instance, error)

	// AdminGetInstancesMetadata retrieves metadata for all instances across all projects.
	// This is an administrative endpoint that returns lightweight instance information.
	// Returns a slice of Instance pointers containing only metadata fields and any error encountered.
	AdminGetInstancesMetadata(ctx context.Context) ([]*models.Instance, error)

	// HealthCheck performs a health check against the API.
	// Returns a map of component names to their status and any error encountered.
	// A successful response typically includes entries like {"status": "ok"}.
	HealthCheck(ctx context.Context) (map[string]string, error)

	// GetInstances retrieves instances with optional filtering via ListOptions.
	// The opts parameter can include pagination (limit/offset), status filtering,
	// and whether to include deleted instances.
	// Returns a slice of Instance pointers and any error encountered.
	GetInstances(ctx context.Context, opts *models.ListOptions) ([]*models.Instance, error)

	// GetInstancesMetadata retrieves metadata for instances with optional filtering.
	// Similar to GetInstances but returns only essential metadata fields for efficiency.
	// Returns a slice of Instance pointers with metadata fields and any error encountered.
	GetInstancesMetadata(ctx context.Context, opts *models.ListOptions) ([]*models.Instance, error)

	// GetInstancesPublicIPs retrieves public IP addresses for instances with optional filtering.
	// Returns a PublicIPsResponse containing a map of instance IDs to their public IPs,
	// and any error encountered.
	GetInstancesPublicIPs(ctx context.Context, opts *models.ListOptions) (types.PublicIPsResponse, error)

	// GetInstance retrieves a specific instance by its ID.
	// Returns the Instance and any error encountered.
	GetInstance(ctx context.Context, id string) (models.Instance, error)

	// CreateInstance creates new instances based on the provided specifications.
	// The req parameter is a slice of InstanceRequest objects, each describing
	// an instance to be created.
	// Returns a slice of the created Instance pointers and any error encountered.
	CreateInstance(ctx context.Context, req []types.InstanceRequest) ([]*models.Instance, error)

	// DeleteInstances terminates the specified instances for a project.
	// The req parameter contains the project name and instance IDs to delete.
	// Returns an error if the operation fails.
	DeleteInstances(ctx context.Context, req types.DeleteInstancesRequest) error

	// GetUserByID retrieves a user by their ID.
	// Returns the User and any error encountered.
	GetUserByID(ctx context.Context, params handlers.UserGetByIDParams) (models.User, error)

	// GetUsers retrieves users based on the provided parameters.
	// Returns a UserResponse containing user information and any error encountered.
	GetUsers(ctx context.Context, params handlers.UserGetParams) (types.UserResponse, error)

	// CreateUser creates a new user with the provided parameters.
	// Returns a CreateUserResponse containing the created user information and any error encountered.
	CreateUser(ctx context.Context, params handlers.CreateUserParams) (types.CreateUserResponse, error)

	// DeleteUser deletes a user based on the provided parameters.
	// Returns an error if the operation fails.
	DeleteUser(ctx context.Context, params handlers.DeleteUserParams) error

	// CreateProject creates a new project with the provided parameters.
	// Returns the created Project and any error encountered.
	CreateProject(ctx context.Context, params handlers.ProjectCreateParams) (models.Project, error)

	// GetProject retrieves a project by name.
	// Returns the Project and any error encountered.
	GetProject(ctx context.Context, params handlers.ProjectGetParams) (models.Project, error)

	// ListProjects lists all projects based on the provided parameters.
	// Returns a slice of Project pointers and any error encountered.
	ListProjects(ctx context.Context, params handlers.ProjectListParams) ([]*models.Project, error)

	// DeleteProject deletes a project by name.
	// Returns an error if the operation fails.
	DeleteProject(ctx context.Context, params handlers.ProjectDeleteParams) error

	// ListProjectInstances lists all instances for a specific project.
	// Returns a slice of Instance pointers and any error encountered.
	ListProjectInstances(ctx context.Context, params handlers.ProjectListInstancesParams) ([]*models.Instance, error)

	// GetTask retrieves a task by its identifier.
	// Returns the Task and any error encountered.
	GetTask(ctx context.Context, params handlers.TaskGetParams) (models.Task, error)

	// ListTasks lists all tasks based on the provided parameters.
	// Returns a slice of Task pointers and any error encountered.
	ListTasks(ctx context.Context, params handlers.TaskListParams) ([]*models.Task, error)

	// ListTasksByInstanceID retrieves tasks for a specific instance ID.
	// Parameters:
	// - ownerID: The ID of the user who owns the instance
	// - instanceID: The ID of the instance to list tasks for
	// - actionFilter: Optional filter for task action type (e.g., "create_instances")
	// - opts: Optional pagination parameters
	// Returns a slice of Task pointers and any error encountered.
	ListTasksByInstanceID(ctx context.Context, ownerID uint, instanceID uint, actionFilter string, opts *models.ListOptions) ([]*models.Task, error)

	// TerminateTask terminates a running task.
	// Returns an error if the operation fails.
	TerminateTask(ctx context.Context, params handlers.TaskTerminateParams) error

	// UpdateTaskStatus updates the status of a task.
	// Returns an error if the operation fails.
	UpdateTaskStatus(ctx context.Context, params handlers.TaskUpdateStatusParams) error
}

type Options struct {
	// BaseURL is the base URL of the API.
	// This should include the protocol (http:// or https://) and host,
	// but not the endpoint paths (e.g., "https://api.example.com").
	BaseURL string

	// APIKey is the API key for authentication.
	// If provided, this key will be included in all API requests.
	APIKey string

	// Timeout is the default request timeout.
	// This value is used when no deadline is set in the context.
	// If not specified, DefaultTimeout (30 seconds) is used.
	Timeout time.Duration
}