types.go

package cursor

import (
	"encoding/json"
	"time"
)

const (
	defaultBaseURL   = "https://api.cursor.com"
	defaultUserAgent = "cursor-go-sdk"
)

// Bool returns a pointer to b. It is useful for optional API booleans.
func Bool(b bool) *bool {
	return &b
}

// String returns a pointer to s.
func String(s string) *string {
	return &s
}

// Int returns a pointer to i.
func Int(i int) *int {
	return &i
}

// AgentOptions configure the high-level cloud Agent facade.
//
// The public Cloud Agents REST API creates the durable agent together with the
// first prompt. When InitialPrompt is empty, CreateAgent returns a lazy handle
// and the first Send call creates the cloud agent.
type AgentOptions struct {
	APIKey       string
	BaseURL      string
	HTTPClient   HTTPDoer
	UserAgent    string
	WaitInterval time.Duration

	Name          string
	Model         ModelSelection
	Cloud         CloudOptions
	MCPServers    map[string]MCPServerConfig
	Agents        map[string]AgentDefinition
	AgentID       string
	InitialPrompt *SDKUserMessage
}

// CloudOptions describe the cloud runtime configuration.
type CloudOptions struct {
	Env                 *AgentEnv
	Repos               []Repo
	BranchName          string
	AutoGenerateBranch  *bool
	AutoCreatePR        *bool
	SkipReviewerRequest *bool
	EnvVars             map[string]string
	WorkOnCurrentBranch *bool
}

// AgentEnv identifies the environment used by a cloud agent.
type AgentEnv struct {
	Type string `json:"type,omitempty"`
	Name string `json:"name,omitempty"`
}

// Repo configures a Git repository for a cloud agent.
type Repo struct {
	URL         string `json:"url,omitempty"`
	StartingRef string `json:"startingRef,omitempty"`
	PRURL       string `json:"prUrl,omitempty"`
}

// PromptInput is the REST prompt shape accepted by the Cloud Agents API.
type PromptInput struct {
	Text   string   `json:"text"`
	Images []string `json:"images,omitempty"`
}

// SDKUserMessage is the TypeScript-style message shape. For the REST-backed
// cloud SDK, images with Data are sent as base64 strings. URL images are
// rejected because the documented REST API accepts base64 image inputs.
type SDKUserMessage struct {
	Text   string     `json:"text"`
	Images []SDKImage `json:"images,omitempty"`
}

// SDKImageDimension optionally describes an image size.
type SDKImageDimension struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

// SDKImage is the TypeScript-style image input shape.
type SDKImage struct {
	URL       string             `json:"url,omitempty"`
	Data      string             `json:"data,omitempty"`
	MimeType  string             `json:"mimeType,omitempty"`
	Dimension *SDKImageDimension `json:"dimension,omitempty"`
}

// ModelSelection selects a Cursor model and optional model-specific params.
type ModelSelection struct {
	ID     string                `json:"id,omitempty"`
	Params []ModelParameterValue `json:"params,omitempty"`
}

// ModelParameterValue is a selected per-model parameter value.
type ModelParameterValue struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

// ModelParameterDefinition describes available values for a model parameter.
type ModelParameterDefinition struct {
	ID          string             `json:"id"`
	DisplayName string             `json:"displayName,omitempty"`
	Values      []ModelParamChoice `json:"values,omitempty"`
}

// ModelParamChoice is one allowed value for a model parameter.
type ModelParamChoice struct {
	Value       string `json:"value"`
	DisplayName string `json:"displayName,omitempty"`
}

// ModelVariant is a preset collection of model parameters.
type ModelVariant struct {
	Params      []ModelParameterValue `json:"params,omitempty"`
	DisplayName string                `json:"displayName"`
	Description string                `json:"description,omitempty"`
	IsDefault   bool                  `json:"isDefault,omitempty"`
}

// ModelListItem is returned by ListModels. It accepts both the richer
// TypeScript SDK catalog shape and the REST beta's string-only examples.
type ModelListItem struct {
	ID          string                     `json:"id"`
	DisplayName string                     `json:"displayName,omitempty"`
	Description string                     `json:"description,omitempty"`
	Parameters  []ModelParameterDefinition `json:"parameters,omitempty"`
	Variants    []ModelVariant             `json:"variants,omitempty"`
}

// UnmarshalJSON accepts either "model-id" or a full model object.
func (m *ModelListItem) UnmarshalJSON(data []byte) error {
	var id string
	if err := json.Unmarshal(data, &id); err == nil {
		m.ID = id
		return nil
	}

	type modelListItem ModelListItem
	var item modelListItem
	if err := json.Unmarshal(data, &item); err != nil {
		return err
	}
	*m = ModelListItem(item)
	return nil
}

// MCPServerConfig mirrors the TypeScript SDK option shape. The public REST API
// may ignore or reject fields it does not yet support.
type MCPServerConfig struct {
	Type    string            `json:"type,omitempty"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	CWD     string            `json:"cwd,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	Auth    *MCPAuth          `json:"auth,omitempty"`
}

// MCPAuth describes OAuth settings for an MCP server.
type MCPAuth struct {
	ClientID     string   `json:"CLIENT_ID"`
	ClientSecret string   `json:"CLIENT_SECRET,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
}

// AgentDefinition mirrors the TypeScript SDK subagent option shape.
type AgentDefinition struct {
	Description string          `json:"description"`
	Prompt      string          `json:"prompt"`
	Model       json.RawMessage `json:"model,omitempty"`
	MCPServers  json.RawMessage `json:"mcpServers,omitempty"`
}

// AgentStatus is the durable agent lifecycle status.
type AgentStatus string

const (
	AgentStatusActive   AgentStatus = "ACTIVE"
	AgentStatusArchived AgentStatus = "ARCHIVED"
)

// AgentInfo is durable cloud agent metadata.
type AgentInfo struct {
	ID                 string      `json:"id"`
	Name               string      `json:"name,omitempty"`
	Summary            string      `json:"summary,omitempty"`
	Status             AgentStatus `json:"status,omitempty"`
	Env                *AgentEnv   `json:"env,omitempty"`
	Repos              []Repo      `json:"repos,omitempty"`
	BranchName         string      `json:"branchName,omitempty"`
	AutoGenerateBranch bool        `json:"autoGenerateBranch,omitempty"`
	AutoCreatePR       bool        `json:"autoCreatePR,omitempty"`
	URL                string      `json:"url,omitempty"`
	CreatedAt          string      `json:"createdAt,omitempty"`
	UpdatedAt          string      `json:"updatedAt,omitempty"`
	LatestRunID        string      `json:"latestRunId,omitempty"`
	Archived           bool        `json:"archived,omitempty"`
}

// AgentID returns the stable agent identifier.
func (a AgentInfo) AgentID() string {
	return a.ID
}

// RunStatus is a cloud run lifecycle status.
type RunStatus string

const (
	RunStatusCreating  RunStatus = "CREATING"
	RunStatusRunning   RunStatus = "RUNNING"
	RunStatusFinished  RunStatus = "FINISHED"
	RunStatusError     RunStatus = "ERROR"
	RunStatusCancelled RunStatus = "CANCELLED"
	RunStatusExpired   RunStatus = "EXPIRED"
)

// Terminal reports whether the status is terminal.
func (s RunStatus) Terminal() bool {
	switch s {
	case RunStatusFinished, RunStatusError, RunStatusCancelled, RunStatusExpired,
		RunStatus("finished"), RunStatus("error"), RunStatus("cancelled"):
		return true
	default:
		return false
	}
}

// RunGitInfo contains cloud git metadata when the API returns it.
type RunGitInfo struct {
	Branches []RunGitBranch `json:"branches,omitempty"`
}

// RunGitBranch describes a branch or PR created by a cloud run.
type RunGitBranch struct {
	RepoURL string `json:"repoUrl,omitempty"`
	Branch  string `json:"branch,omitempty"`
	PRURL   string `json:"prUrl,omitempty"`
}

// RunResult is returned by Run.Wait.
type RunResult struct {
	ID         string          `json:"id"`
	AgentID    string          `json:"agentId,omitempty"`
	Status     RunStatus       `json:"status"`
	Result     string          `json:"result,omitempty"`
	Model      *ModelSelection `json:"model,omitempty"`
	DurationMS int64           `json:"durationMs,omitempty"`
	Git        RunGitInfo      `json:"git,omitempty"`
	CreatedAt  string          `json:"createdAt,omitempty"`
	UpdatedAt  string          `json:"updatedAt,omitempty"`
}

// Artifact is an agent-scoped file produced under the artifacts/ directory.
type Artifact struct {
	Path      string `json:"path"`
	SizeBytes int64  `json:"sizeBytes"`
	UpdatedAt string `json:"updatedAt"`
}

// ArtifactDownload contains a temporary presigned artifact URL.
type ArtifactDownload struct {
	URL       string `json:"url"`
	ExpiresAt string `json:"expiresAt"`
}

// Repository describes a GitHub repository connected to Cursor.
type Repository struct {
	URL string `json:"url"`
}

// User describes the API key owner.
type User struct {
	APIKeyName string `json:"apiKeyName"`
	CreatedAt  string `json:"createdAt"`
	UserEmail  string `json:"userEmail,omitempty"`
}

// SubToken identifies a short-lived user-scoped worker token.
type SubToken struct {
	AccessToken string `json:"accessToken"`
	ExpiresAt   string `json:"expiresAt"`
	UserID      int    `json:"userId"`
	TeamID      int    `json:"teamId"`
}