core

type Action interface {

	/*
	 * The unique identifier for the component.
	 * This is how nodes reference it, and is used for registration.
	 */
	Name() string

	/*
	 * The label for the component.
	 * This is how nodes are displayed in the UI.
	 */
	Label() string

	/*
	 * A good description of what the component does.
	 * Helpful for documentation and user interfaces.
	 */
	Description() string

	/*
	 * Detailed markdown documentation explaining how to use the component.
	 * This should provide in-depth information about the component's purpose,
	 * configuration options, use cases, and examples.
	 */
	Documentation() string

	/*
	 * The icon for the component.
	 * This is used in the UI to represent the component.
	 */
	Icon() string

	/*
	 * The color for the component.
	 * This is used in the UI to represent the component.
	 */
	Color() string

	/*
	 * Example output data for the component.
	 */
	ExampleOutput() map[string]any

	/*
	 * The output channels used by the component.
	 * If none is returned, the 'default' one is used.
	 */
	OutputChannels(configuration any) []OutputChannel

	/*
	 * The configuration fields exposed by the component.
	 */
	Configuration() []configuration.Field

	/*
	 * Setup the component.
	 */
	Setup(ctx SetupContext) error

	/*
	 * Passes full execution control to the component.
	 *
	 * Component execution has full control over the execution state,
	 * so it is the responsibility of the component to control it.
	 *
	 * Components should finish the execution or move it to waiting state.
	 * Components can also implement async components by combining Execute() and HandleHook().
	 */
	Execute(ctx ExecutionContext) error

	/*
	 * Allows components to define and execute custom hooks.
	 */
	Hooks() []Hook
	HandleHook(ctx ActionHookContext) error

	/*
	 * Handler for webhooks.
	 */
	HandleWebhook(ctx WebhookRequestContext) (int, *WebhookResponseBody, error)

	/*
	 * Cancel allows components to handle cancellation of executions.
	 * Default behavior does nothing. Components can override to perform
	 * cleanup or cancel external resources.
	 */
	Cancel(ctx ExecutionContext) error

	/*
	 * Cleanup allows components to clean up resources after being removed from a canvas.
	 * Default behavior does nothing. Components can override to perform cleanup.
	 */
	Cleanup(ctx SetupContext) error
}

type ActionHookContext struct {
	Name           string
	Configuration  any
	Parameters     map[string]any
	Logger         *log.Entry
	HTTP           HTTPContext
	Metadata       MetadataWriter
	ExecutionState ExecutionStateContext
	Auth           AuthReader
	Requests       RequestContext
	Integration    IntegrationContext
	Secrets        SecretsContext
	Runs           RunExecutionContext
	Factory        FactoryContext
	Usage          UsageRecorder
	HostedLLM      HostedLLMContext
	RunnerTasks    RunnerTaskContext
}

type AddPullRequestActivityParams struct {
	PullRequestID string
	Title         string
	Description   string
	Revision      string
	Access        string
}

type AddPullRequestParams struct {
	OrderID    string
	Provider   string
	ExternalID string
	Repository string
	Number     int64
	URL        string
	Title      string
	State      string
	MergedAt   *time.Time
	ClosedAt   *time.Time
}

type AddWorkOrderArtifactParams struct {
	// OrderID identifies the work order to target; see
	// UpdateWorkOrderStatusParams.OrderID.
	OrderID string
	Type    string
	Data    map[string]any
	// Key optionally tags the artifact with a queryable key so a later
	// FindWorkOrder(by: artifactKey) can resolve the work order from it.
	// When set, AddWorkOrderArtifact creates the artifact on the first
	// call and replaces its data on later calls. Replacement is
	// wholesale: fields absent from the later call are cleared. The
	// first call sets the type; a later call with a different type
	// fails. Keys are unique per factory.
	Key string
	// UpdateByTitle replaces the newest unkeyed artifact on this task
	// with the same type and title. Keyed rows stay unchanged. The
	// first call creates an unkeyed row when none exists. A blank
	// title fails. This flag does not use Key.
	UpdateByTitle bool
}

type AddWorkOrderCommentParams struct {
	// OrderID identifies the work order to target; see
	// UpdateWorkOrderStatusParams.OrderID.
	OrderID string
	Body    string
}

type App struct {
	ID   string
	Name string
}

type AppContext interface {
	Get(idOrName string) (*App, error)
	GetNode(app, node string) (*CanvasNode, error)
	Subscribe(id string) error
	Unsubscribe() error
}

type AppExecutionContext interface {
	Broadcast(payload any) error
}

type AppMessageContext struct {
	Message       any
	Configuration any
	NodeMetadata  MetadataReader
	Logger        *log.Entry
	HTTP          HTTPContext
	Events        EventContext
}

type AppTrigger interface {
	Trigger
	OnAppMessage(ctx AppMessageContext) error
}

type AuthReader interface {
	AuthenticatedUser() *User
	GetUser(id uuid.UUID) (*User, error)
	GetRole(name string) (*RoleRef, error)
	GetGroup(name string) (*GroupRef, error)
	HasRole(role string) (bool, error)
	InGroup(group string) (bool, error)
}

type BrowserAction struct {
	Description string
	URL         string
	Method      string
	FormFields  map[string]string
}

type CanvasMemoryContext interface {
	Add(namespace string, values any) error
	Find(namespace string, matches map[string]any) ([]any, error)
	FindFirst(namespace string, matches map[string]any) (any, error)
}

type CanvasMemoryRecord struct {
	ID     uuid.UUID
	Values any
}

type CanvasNode struct {
	ID   string
	Name string
}

type Capability struct {
	Type           IntegrationCapabilityType `json:"type"`
	Name           string                    `json:"name"`
	Label          string                    `json:"label"`
	Description    string                    `json:"description"`
	Configuration  []configuration.Field     `json:"configuration"`
	OutputChannels []OutputChannel           `json:"outputChannels"`
	ExampleOutput  map[string]any            `json:"exampleOutput,omitempty"`
	ExampleData    map[string]any            `json:"exampleData,omitempty"`
}

type CapabilityContext interface {
	Request(capabilities ...string)
	Available(capabilities ...string)
	Unavailable(capabilities ...string)
	Enable(capabilities ...string)
	Disable(capabilities ...string)
	Clear()
	IsRequested(capabilities ...string) bool
	Requested() []string
	Enabled() []string
}

type CapabilityGroup struct {
	Label        string
	Capabilities []Capability
}

type CapabilityUpdateContext struct {
	Changes      map[IntegrationCapabilityState][]string
	Logger       *log.Entry
	HTTP         HTTPContext
	Secrets      IntegrationSecretStorage
	Properties   IntegrationPropertyStorage
	Capabilities CapabilityContext
}

type ComputeUsageRecord struct {
	MachineType     string
	FleetID         string
	DurationSeconds int64
	IdempotencyKey  string
}

type Configurable interface {
	Configuration() []configuration.Field
}

type DefaultHostedLLMModel struct {
	Provider string
	Model    string
}

type EventContext interface {
	Emit(payloadType string, payload any) error
}

type ExecutionContext struct {
	ID             uuid.UUID
	RunID          uuid.UUID
	WorkflowID     string
	OrganizationID string
	CanvasName     string
	NodeID         string
	NodeName       string
	SourceNodeID   string
	BaseURL        string
	Data           any
	Configuration  any
	Logger         *log.Entry
	HTTP           HTTPContext
	Metadata       MetadataWriter
	NodeMetadata   MetadataReader
	ExecutionState ExecutionStateContext
	Requests       RequestContext
	Auth           AuthReader
	Integration    IntegrationContext
	Secrets        SecretsContext
	CanvasMemory   CanvasMemoryContext
	Webhook        NodeWebhookContext
	Expressions    ExpressionContext
	OIDC           oidc.Provider
	Apps           AppExecutionContext
	Runs           RunExecutionContext
	Factory        FactoryContext
	Usage          UsageRecorder
	HostedLLM      HostedLLMContext
	RunnerTasks    RunnerTaskContext
}

type ExecutionStateContext interface {
	IsFinished() bool
	IsCancelling() bool
	SetKV(key, value string) error
	GetKV(key string) (string, error)

	/*
	 * Pass the execution, emitting a payload to the specified channel.
	 */
	Emit(channel, payloadType string, payloads []any) error

	/*
	 * Emit a payload but keep the execution active for further work.
	 */
	EmitAndContinue(channel, payloadType string, payloads []any) error

	/*
	 * Pass the execution, without emitting any payloads from it.
	 */
	Pass() error

	/*
	 * Fails the execution.
	 * No payloads are emitted.
	 */
	Fail(reason, message string) error

	/*
	 * Cancels the execution.
	 * No payloads are emitted.
	 */
	Cancel() error
}

type ExpressionContext interface {
	Run(expression string) (any, error)
	RunWithExtraVariables(expression string, variables map[string]any) (any, error)
}

type FactoryContext interface {
	// CreateWorkOrder reports whether a row was inserted via the second
	// return value; callers must skip downstream emits when `created` is
	// false so a duplicate Sentry intake item does not leak into the
	// timeline.
	CreateWorkOrder(params WorkOrderParams) (order *WorkOrder, created bool, err error)
	// FindWorkOrder resolves a work order by id or by one of its
	// artifacts' keys, without requiring the current run to be attached
	// to a `factory_work_order_executions` row. Returns ErrWorkOrderNotFound
	// (wrapped) when nothing matches.
	FindWorkOrder(params FindWorkOrderParams) (*WorkOrder, error)
	// UpdateWorkOrderStatus reports whether the row actually transitioned
	// via the second return value; callers must skip downstream emits
	// when `changed` is false so a no-op doesn't leak into the timeline.
	UpdateWorkOrderStatus(params UpdateWorkOrderStatusParams) (order *WorkOrder, changed bool, err error)
	AddWorkOrderComment(params AddWorkOrderCommentParams) error
	AddWorkOrderArtifact(params AddWorkOrderArtifactParams) (*WorkOrderArtifact, error)
	// ReportWorkOrderCheck upserts a scored check on the work order,
	// keyed by CheckKey: the first report creates the check, later
	// reports with the same key update it in place and keep the prior
	// score as PreviousScore. Every report also lands an
	// `order.check.reported` timeline event.
	ReportWorkOrderCheck(params ReportWorkOrderCheckParams) (*WorkOrderCheck, error)
	// SetWorkOrderStatusNote upserts a status note on the work order,
	// keyed by NoteKey: the first set creates the note, later sets with
	// the same key update it in place, and a different key sits beside
	// it. Any lifecycle transition clears the whole set. The order must
	// be open.
	SetWorkOrderStatusNote(params SetWorkOrderStatusNoteParams) (*WorkOrderStatusNote, error)
	AddPullRequest(params AddPullRequestParams) (*PullRequest, error)
	UpdatePullRequest(params UpdatePullRequestParams) (*PullRequest, error)
	FindPullRequest(params FindPullRequestParams) (*PullRequestMatch, error)
	AddPullRequestActivity(params AddPullRequestActivityParams) (*PullRequestActivityResult, error)
	UpdatePullRequestActivity(params UpdatePullRequestActivityParams) (*PullRequestActivityResult, error)
	// VCSProvider returns the workspace Git host from factory onboarding.
	// An empty value means GitHub. A caller that has no factory gets an
	// empty value and keeps GitHub branch links.
	VCSProvider() (string, error)
}

type FindPullRequestParams struct {
	ID         string
	Provider   string
	ExternalID string
	Repository string
	Number     int64
	URL        string
}

type FindWorkOrderParams struct {
	By          string
	OrderID     string
	ArtifactKey string
}

type GroupRef struct {
	Name        string `mapstructure:"name" json:"name"`
	DisplayName string `mapstructure:"displayName" json:"displayName"`
}

type HTTPContext interface {
	Do(*http.Request) (*http.Response, error)
}

type HTTPRequestContext struct {
	Logger           *logrus.Entry
	Request          *http.Request
	Response         http.ResponseWriter
	OrganizationID   string
	BaseURL          string
	WebhooksBaseURL  string
	HTTP             HTTPContext
	Integration      IntegrationContext
	Capabilities     CapabilityContext
	IntegrationSetup IntegrationSetupContext
}

type Hook struct {
	Type       HookType
	Name       string
	Parameters []configuration.Field
}

type HookType string

type HostedLLMAccess struct {
	APIKey        string
	ManagementKey string
	BaseURL       string
	AllowedModels []string
}

type HostedLLMContext interface {
	Resolve(provider string) (HostedLLMAccess, error)
	AssertCreditAvailable() error
	AssertModelSelectable(provider, fundingSource, model string) error
	DefaultModel() (DefaultHostedLLMModel, error)
}

type Integration interface {
	/*
	 * The name of the integration.
	 */
	Name() string

	/*
	 * Display name for the integration.
	 */
	Label() string

	/*
	 * The icon used by the integration.
	 */
	Icon() string

	/*
	 * A description of what the integration does.
	 */
	Description() string

	/*
	 * Markdown-formatted instructions shown in the connection modal.
	 */
	Instructions() string

	/*
	 * The configuration fields of the integration.
	 */
	Configuration() []configuration.Field

	/*
	 * The list of actions exposed by the integration.
	 */
	Actions() []Action

	/*
	 * The list of triggers exposed by the integration.
	 */
	Triggers() []Trigger

	/*
	 * Called when configuration changes.
	 */
	Sync(ctx SyncContext) error

	/*
	 * Called when the integration is deleted.
	 */
	Cleanup(ctx IntegrationCleanupContext) error

	/*
	 * Allows integrations to define and execute  hooks.
	 */
	Hooks() []Hook
	HandleHook(ctx IntegrationHookContext) error

	/*
	 * List resources of a given type.
	 */
	ListResources(resourceType string, ctx ListResourcesContext) ([]IntegrationResource, error)

	/*
	 * HTTP request handler
	 */
	HandleRequest(ctx HTTPRequestContext)
}

type IntegrationAction interface {

	/*
	 * IntegrationAction inherits all the methods from Action interface,
	 * and adds a couple more, which are only applicable to app actions.
	 */
	Action

	OnIntegrationMessage(ctx IntegrationMessageContext) error
}

type IntegrationCapabilityState string

type IntegrationCapabilityType string

type IntegrationCleanupContext struct {
	Configuration  any
	BaseURL        string
	OrganizationID string
	Logger         *logrus.Entry
	HTTP           HTTPContext
	Integration    IntegrationContext
}

type IntegrationContext interface {

	//
	// Whether the integration is using the legacy setup flow.
	//
	LegacySetup() bool
	Properties() IntegrationPropertyStorage
	Secrets() IntegrationSecretStorage

	//
	// Control the metadata and config of the integration
	//
	ID() uuid.UUID
	GetMetadata() any
	SetMetadata(any)
	GetConfig(name string) ([]byte, error)

	//
	// Control the state of the integration
	//
	Ready()
	Error(message string)

	//
	// Control the browser action of the integration
	//
	NewBrowserAction(action BrowserAction)
	RemoveBrowserAction()

	//
	// Control the secrets of the integration
	//
	SetSecret(name string, value []byte) error
	GetSecrets() ([]IntegrationSecret, error)

	/*
	 * Request a new webhook from the integration.
	 * Called from the components/triggers Setup().
	 */
	RequestWebhook(configuration any) error

	/*
	 * Subscribe to integration events.
	 */
	Subscribe(any) (*uuid.UUID, error)

	/*
	 * Schedule actions for the integration.
	 */
	ScheduleResync(interval time.Duration) error
	ScheduleActionCall(actionName string, parameters any, interval time.Duration) error

	/*
	 * List integration subscriptions from nodes.
	 */
	ListSubscriptions() ([]IntegrationSubscriptionContext, error)

	// ListNodeConfigurations returns the configuration of each non-deleted
	// node that uses this integration on an active canvas.
	ListNodeConfigurations() ([]any, error)

	/*
	 * Find a subscription by a predicate function.
	 * Returns the first subscription that matches the predicate, or nil if none found.
	 */
	FindSubscription(predicate func(IntegrationSubscriptionContext) bool) (IntegrationSubscriptionContext, error)
}

type IntegrationHookContext struct {
	Name            string
	Parameters      any
	Configuration   any
	WebhooksBaseURL string
	Logger          *log.Entry
	Requests        RequestContext
	Integration     IntegrationContext
	HTTP            HTTPContext
}

type IntegrationMessageContext struct {
	Message           any
	Configuration     any
	NodeMetadata      MetadataReader
	Logger            *logrus.Entry
	HTTP              HTTPContext
	Integration       IntegrationContext
	Events            EventContext
	FindExecutionByKV func(key string, value string) (*ExecutionContext, error)
}

type IntegrationPropertyDefinition struct {
	Type        IntegrationPropertyType `json:"type"`
	Name        string                  `json:"name"`
	Label       string                  `json:"label"`
	Description string                  `json:"description"`
	Value       any                     `json:"value"`
	Editable    bool                    `json:"editable"`
}

type IntegrationPropertyStorage interface {
	IntegrationPropertyStorageReader

	Delete(names ...string) error
	Create(def IntegrationPropertyDefinition) error
	CreateMany(defs []IntegrationPropertyDefinition) error
}

type IntegrationPropertyStorageReader interface {
	Get(name string) (any, error)
	GetString(name string) (string, error)
}

type IntegrationPropertyType string

type IntegrationResource struct {
	Type string
	Name string
	ID   string
	URL  string
}

type IntegrationSecret struct {
	Name  string
	Value []byte
}

type IntegrationSecretContext struct {
	Logger      *logrus.Entry
	HTTP        HTTPContext
	Integration IntegrationContext
}

type IntegrationSecretDefinition struct {
	Name        string
	Label       string
	Description string
	Value       string
	Editable    bool
}

type IntegrationSecretProvider interface {
	ResolveSecrets(ctx IntegrationSecretContext) (IntegrationSecrets, error)
}

type IntegrationSecretStorage interface {
	IntegrationSecretStorageReader

	Delete(name string) error
	Create(def IntegrationSecretDefinition) error
	CreateMany(defs []IntegrationSecretDefinition) error
	Update(name string, value string) error
}

type IntegrationSecretStorageReader interface {
	Get(name string) (string, error)
}

type IntegrationSecrets struct {
	Values    map[string][]byte
	Usage     string
	Setup     string
	SetupName string
}

type IntegrationSetupContext interface {
	SetStep(step SetupStep) error
}

type IntegrationSetupProvider interface {

	//
	// All the capabilities supported by the integration.
	// The grouping is a presentation matter, and per-integration states
	// are still tracked per capability.
	//
	CapabilityGroups() []CapabilityGroup

	//
	// Generate the first step of the setup flow.
	//
	FirstStep(ctx SetupStepContext) SetupStep

	//
	// Called when the user submits the current pending step.
	//
	OnStepSubmit(ctx SetupStepContext) (*SetupStep, error)

	//
	// Called when the user reverts the last successfully submitted step.
	//
	OnStepRevert(ctx SetupStepContext) error

	//
	// Called when the user updates a property.
	// A property update might trigger a new setup flow.
	//
	OnPropertyUpdate(ctx PropertyUpdateContext) (*SetupStep, error)

	//
	// Called when the user updates a secret.
	// A secret update might trigger a new setup flow.
	//
	OnSecretUpdate(ctx SecretUpdateContext) (*SetupStep, error)

	//
	// Called when the user requests new capabilities
	// from an already setup integration.
	//
	OnCapabilityUpdate(ctx CapabilityUpdateContext) (*SetupStep, error)
}

type IntegrationSubscriptionContext interface {
	Configuration() any
	SendMessage(any) error
}

type IntegrationTrigger interface {

	/*
	 * Inherits all the methods from Trigger interface,
	 * and adds a couple more, which are only applicable to integration triggers.
	 */
	Trigger

	OnIntegrationMessage(ctx IntegrationMessageContext) error
}

type ListResourcesContext struct {
	Logger      *logrus.Entry
	HTTP        HTTPContext
	Integration IntegrationContext
	Parameters  map[string]string
}

type MetadataReader interface {
	Get() any
}

type MetadataWriter interface {
	MetadataReader
	Set(any) error
}

type Node struct {
	ID string `mapstructure:"id" json:"id"`
}

type NodeConfigurationValidator interface {
	ValidateNodeConfiguration(config map[string]any) error
}

type NodeWebhookContext interface {
	Setup() (string, error)
	GetSecret() ([]byte, error)
	SetSecret(secret []byte) error
	ResetSecret() ([]byte, []byte, error)
	GetBaseURL() string
}

type OutputChannel struct {
	Name        string
	Label       string
	Description string
}

type ProcessQueueContext struct {
	WorkflowID    string
	NodeID        string
	RootEventID   string
	EventID       string
	SourceNodeID  string
	Configuration any
	Input         any
	Expressions   ExpressionContext

	//
	// Deletes the queue item
	//
	DequeueItem func() error

	//
	// Defers the queue item by moving it to the back of the node queue.
	//
	DeferQueueItem func() error

	//
	// Updates the state of the node
	//
	UpdateNodeState func(state string) error

	//
	// Creates a pending execution for this queue item.
	//
	CreateExecution func() (*ExecutionContext, error)

	//
	// Finds an execution by a key-value pair.
	// Returns an ExecutionContext.
	//
	FindExecutionByKV func(key string, value string) (*ExecutionContext, error)

	//
	// MaxConcurrency is the node's effective concurrency max.
	// Self-managed components use it to gate how much concurrent work
	// they start, since the queue worker does not capacity-gate their
	// queue items.
	//
	MaxConcurrency int

	//
	// CountRunningExecutions returns how many executions of this node
	// currently occupy a concurrency slot: pending, started, or
	// cancelling. Pending counts so that items processed in the same
	// pass cannot all pass a limit check before any execution starts.
	//
	CountRunningExecutions func() (int64, error)

	//
	// DistinctIncomingSources returns the distinct upstream
	// source nodes connected to this node (ignoring multiple channels from the
	// same source)
	//
	DistinctIncomingSources func() ([]Node, error)
}

type PropertyUpdateContext struct {
	PropertyName string
	Value        string
	Logger       *log.Entry
	HTTP         HTTPContext
	Secrets      IntegrationSecretStorage
	Properties   IntegrationPropertyStorage
	Capabilities CapabilityContext
}

type ProviderAPIError struct {
	// StatusCode is the HTTP status code returned by the provider. It is zero
	// for transport-level failures (network error, timeout) that never
	// received a response.
	StatusCode int
	// contains filtered or unexported fields
}

type PullRequest struct {
	ID          string `json:"id"`
	WorkOrderID string `json:"workOrderId"`
	Provider    string `json:"provider"`
	ExternalID  string `json:"externalId,omitempty"`
	Repository  string `json:"repository"`
	Number      int64  `json:"number"`
	URL         string `json:"url"`
	Title       string `json:"title,omitempty"`
	State       string `json:"state"`
}

type PullRequestActivity struct {
	Title        string               `json:"title,omitempty"`
	Description  string               `json:"description,omitempty"`
	Access       string               `json:"access"`
	State        string               `json:"state"`
	Attempt      *int                 `json:"attempt,omitempty"`
	AttemptLimit *int                 `json:"attemptLimit,omitempty"`
	Revision     *PullRequestRevision `json:"revision,omitempty"`
}

type PullRequestActivityResult struct {
	PullRequest     *PullRequest
	WorkOrder       *WorkOrder
	Activity        *PullRequestActivity
	CurrentRevision *PullRequestRevision
	CurrentHeadSHA  string
	Outcome         string
}

type PullRequestMatch struct {
	PullRequest *PullRequest
	WorkOrder   *WorkOrder
}

type PullRequestRevision struct {
	SHA        string `json:"sha"`
	ObservedAt string `json:"observedAt,omitempty"`
}

type QueueItemProcessor interface {
	/*
	 * ProcessQueueItem is called when a queue item for this component's
	 * node is ready to be processed. Implementations should create the
	 * appropriate execution or handle the item synchronously using the
	 * provided context.
	 */
	ProcessQueueItem(ctx ProcessQueueContext) (*uuid.UUID, error)
}

type RedirectPrompt struct {
	URL      string
	Method   string
	FormData map[string]string
}

type ReportWorkOrderCheckParams struct {
	// OrderID identifies the work order to target; see
	// UpdateWorkOrderStatusParams.OrderID.
	OrderID string
	// CheckKey identifies the check across reports (e.g. "risk-review").
	CheckKey string
	Name     string
	Score    float64
	MaxScore float64
	Format   string
	Level    string
	Summary  string
	Analysis string
}

type RequestContext interface {

	//
	// Allows the scheduling of a certain component action at a later time
	//
	ScheduleActionCall(actionName string, parameters map[string]any, interval time.Duration) error
}

type RoleRef struct {
	Name        string `mapstructure:"name" json:"name"`
	DisplayName string `mapstructure:"displayName" json:"displayName"`
}

type Run struct {
	ID     uuid.UUID `json:"id" mapstructure:"id"`
	AppID  uuid.UUID `json:"app_id" mapstructure:"app_id"`
	Result string    `json:"result" mapstructure:"result"`
	Errors []string  `json:"errors" mapstructure:"errors"`
}

type RunCallback struct {
	When string `json:"when" mapstructure:"when"`
	On   string `json:"on" mapstructure:"on"`
	Hook string `json:"hook" mapstructure:"hook"`
}

type RunCreationParams struct {
	Input     any
	App       string
	Node      string
	Callbacks []RunCallback
}

type RunExecutionContext interface {
	Create(params RunCreationParams) (*Run, error)
	Cancel() error
	AddError(message string) error
}

type RunFinishedCallback struct {
	Run Run `json:"run" mapstructure:"run"`
}

type RunnerTask struct {
	ID           string
	State        string
	Result       json.RawMessage
	ExitCode     *int
	ErrorMessage string
	ReservedAt   *time.Time
	StartedAt    *time.Time
	FinishedAt   *time.Time
}

type RunnerTaskContext interface {
	IntegratedBackendEnabled() (bool, error)
	Create(id, fleetID string, payload []byte) error
	Find(id string) (*RunnerTask, error)
	RequestCancel(id string) error
}

type SecretUpdateContext struct {
	SecretName   string
	Value        string
	Logger       *log.Entry
	HTTP         HTTPContext
	Secrets      IntegrationSecretStorage
	Properties   IntegrationPropertyStorage
	Capabilities CapabilityContext
}

type SecretsContext interface {
	GetKey(secretName, keyName string) ([]byte, error)
	GetSecretKeys(secretName string) (map[string][]byte, error)
	GetIntegrationSecrets(installationName string) (IntegrationSecrets, error)
}

type SetWorkOrderStatusNoteParams struct {
	// OrderID identifies the work order to target; see
	// UpdateWorkOrderStatusParams.OrderID.
	OrderID string
	// NoteKey identifies the note across sets (e.g. "pr-closure").
	NoteKey             string
	Kind                string
	Headline            string
	Body                string
	CtaLabel            string
	CtaURL              string
	ShowOnlyWhenWaiting bool
}

type SetupContext struct {
	Logger        *log.Entry
	Configuration any
	HTTP          HTTPContext
	Metadata      MetadataWriter
	Requests      RequestContext
	Auth          AuthReader
	Integration   IntegrationContext
	Webhook       NodeWebhookContext
	Apps          AppContext
}

type SetupStep struct {
	Type           SetupStepType
	Name           string
	Label          string
	Instructions   string
	Inputs         []configuration.Field
	Capabilities   []string
	RedirectPrompt *RedirectPrompt
}

type SetupStepContext struct {
	Step            StepInfo
	IntegrationID   uuid.UUID
	OrganizationID  string
	BaseURL         string
	WebhooksBaseURL string
	Logger          *log.Entry
	HTTP            HTTPContext
	Secrets         IntegrationSecretStorage
	Properties      IntegrationPropertyStorage
	Capabilities    CapabilityContext
}

type SetupStepType string

type StepInfo struct {
	Name         string
	Inputs       any
	Capabilities []string
}

type SyncContext struct {
	Logger          *logrus.Entry
	Configuration   any
	BaseURL         string
	WebhooksBaseURL string
	OrganizationID  string
	ActorUserID     string
	HTTP            HTTPContext
	Integration     IntegrationContext
	OIDC            oidc.Provider
}

type Trigger interface {
	/*
	 * The unique identifier for the trigger.
	 * This is how nodes reference it, and is used for registration.
	 */
	Name() string

	/*
	 * The label for the trigger.
	 * This is how nodes are displayed in the UI.
	 */
	Label() string

	/*
	 * A good description of what the trigger does.
	 * Helpful for documentation and user interfaces.
	 */
	Description() string

	/*
	 * Detailed markdown documentation explaining how to use the trigger.
	 * This should provide in-depth information about the trigger's purpose,
	 * configuration options, use cases, and examples.
	 */
	Documentation() string

	/*
	 * The icon for the trigger.
	 */
	Icon() string

	/*
	 * The color for the trigger.
	 */
	Color() string

	/*
	 * Example input data for the trigger.
	 */
	ExampleData() map[string]any

	/*
	 * The configuration fields exposed by the trigger.
	 */
	Configuration() []configuration.Field

	/*
	 * Handler for webhooks
	 */
	HandleWebhook(ctx WebhookRequestContext) (int, *WebhookResponseBody, error)

	/*
	 * Setup the trigger.
	 */
	Setup(ctx TriggerContext) error

	/*
	 * Allows triggers to define custom hooks.
	 */
	Hooks() []Hook

	/*
	 * Execute a custom hook - defined in Hooks() for a trigger.
	 */
	HandleHook(ctx TriggerHookContext) (map[string]any, error)

	/*
	 * Cleanup allows triggers to clean up resources after being removed from a canvas.
	 * Default behavior does nothing. Triggers can override to perform cleanup.
	 */
	Cleanup(ctx TriggerContext) error
}

type TriggerContext struct {
	Logger        *log.Entry
	Configuration any
	HTTP          HTTPContext
	Metadata      MetadataWriter
	Requests      RequestContext
	Events        EventContext
	Webhook       NodeWebhookContext
	Integration   IntegrationContext
	Apps          AppContext
}

type TriggerHookContext struct {
	Name          string
	Parameters    map[string]any
	Configuration any
	Logger        *log.Entry
	HTTP          HTTPContext
	Metadata      MetadataWriter
	Requests      RequestContext
	Events        EventContext
	Webhook       NodeWebhookContext
	Integration   IntegrationContext
}

type UpdatePullRequestActivityParams struct {
	Title       *string
	Description *string
	Access      string
}

type UpdatePullRequestParams struct {
	PullRequestID string
	ExternalID    *string
	Repository    *string
	URL           *string
	Title         *string
	State         *string
	MergedAt      *time.Time
	ClosedAt      *time.Time
}

type UpdateWorkOrderStatusParams struct {
	// OrderID identifies the work order to target. Required; the
	// component field defaults to `{{ order().id }}` (the work order
	// driving the current run) but callers must always resolve and pass
	// an explicit id.
	OrderID string
	State   string
	Result  string
}

type UsageRecord struct {
	Provider         string
	Model            string
	InputTokens      int64
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	ReasoningTokens  int64
	TotalTokens      int64
	// CostMicros is provider-reported cost in millionths of a US dollar.
	// Leave nil to price the call from the SuperPlane price book.
	CostMicros *int64
	// FundingSource is "hosted" or "byok". Empty defaults to byok.
	FundingSource string
	// IdempotencyKey is a stable ledger key. Empty generates a unique key
	// per call. Runner finish records use a prefix so webhook and poll
	// cannot insert two rows for one node execution.
	IdempotencyKey string
}

type UsageRecorder interface {
	Record(record UsageRecord) error
	RecordCompute(record ComputeUsageRecord) error
}

type User struct {
	ID    string `mapstructure:"id" json:"id"`
	Name  string `mapstructure:"name" json:"name"`
	Email string `mapstructure:"email" json:"email"`
}

type WebhookContext interface {
	GetID() string
	GetURL() string
	GetSecret() ([]byte, error)
	GetMetadata() any
	GetConfiguration() any
	SetSecret([]byte) error
	// CallbackHasActiveNodes reports whether webhookID still has live canvas
	// consumers. Jira uses this before taking over a stale remote callback.
	CallbackHasActiveNodes(webhookID string) (bool, error)
}

type WebhookHandler interface {

	/*
	 * Set up webhooks through the integration, in the external system.
	 * This is called by the webhook provisioner, for pending webhook records.
	 */
	Setup(ctx WebhookHandlerContext) (any, error)

	/*
	 * Delete webhooks through the integration, in the external system.
	 * This is called by the webhook cleanup worker, for webhook records that were deleted.
	 */
	Cleanup(ctx WebhookHandlerContext) error

	/*
	 * Compare two webhook configurations to see if they are the same.
	 */
	CompareConfig(a, b any) (bool, error)

	/*
	 * Merge an existing webhook configuration with a requested one.
	 * Return changed=false when no update is needed.
	 */
	Merge(current, requested any) (merged any, changed bool, err error)
}

type WebhookHandlerContext struct {
	Logger      *logrus.Entry
	HTTP        HTTPContext
	Integration IntegrationContext
	Webhook     WebhookContext
}

type WebhookOptions struct {
	ID            string
	URL           string
	Secret        []byte
	Configuration any
	Metadata      any
}

type WebhookRequestContext struct {
	Body          []byte
	Headers       http.Header
	Query         url.Values
	WorkflowID    string
	NodeID        string
	Configuration any
	Metadata      MetadataWriter
	Logger        *log.Entry
	Webhook       NodeWebhookContext
	Events        EventContext
	Integration   IntegrationContext
	Factory       FactoryContext

	//
	// Return an execution context for a given execution,
	// through a referencing key-value pair.
	//
	FindExecutionByKV func(key string, value string) (*ExecutionContext, error)

	//
	// Return the oldest active execution for a key-value pair.
	// Narrowly scoped for Bitbucket build waits, where a completed wait can
	// share a KV with a later active wait. Nil when the caller does not
	// support active lookups; other components keep FindExecutionByKV.
	//
	FindActiveExecutionByKV func(key string, value string) (*ExecutionContext, error)

	// Do not make HTTP calls as part of handling the webhook. This is useful for
	// retrieving more data that is not part of the webhook payload.
	HTTP HTTPContext
}

type WebhookResponseBody struct {
	Body        []byte
	ContentType string
}

type Widget interface {

	/*
	 * The unique identifier for the widget.
	 * This is how nodes reference it, and is used for registration.
	 */
	Name() string

	/*
	 * The label for the widget.
	 * This is how nodes are displayed in the UI.
	 */
	Label() string

	/*
	 * A good description of what the widget does.
	 * Helpful for documentation and user interfaces.
	 */
	Description() string

	/*
	 * The icon for the widget.
	 */
	Icon() string

	/*
	 * The color for the widget.
	 */
	Color() string

	/*
	 * The configuration fields exposed by the widget.
	 */
	Configuration() []configuration.Field
}

type WorkOrder struct {
	ID          string           `json:"id"`
	Title       string           `json:"title"`
	Description string           `json:"description"`
	State       string           `json:"state"`
	Result      string           `json:"result,omitempty"`
	Number      int64            `json:"number,omitempty"`
	Key         string           `json:"key,omitempty"`
	Origin      *WorkOrderOrigin `json:"origin,omitempty"`
}

type WorkOrderArtifact struct {
	ID          string         `json:"id"`
	WorkOrderID string         `json:"workOrderId"`
	Type        string         `json:"type"`
	Data        map[string]any `json:"data,omitempty"`
}

type WorkOrderCheck struct {
	ID            string   `json:"id"`
	WorkOrderID   string   `json:"workOrderId"`
	Key           string   `json:"key"`
	Name          string   `json:"name"`
	Score         float64  `json:"score"`
	MaxScore      float64  `json:"maxScore"`
	Format        string   `json:"format"`
	Level         string   `json:"level"`
	PreviousScore *float64 `json:"previousScore,omitempty"`
	// RecentScores lists the latest report scores, oldest first and
	// ending with Score, capped server-side.
	RecentScores []float64 `json:"recentScores,omitempty"`
}

type WorkOrderOrigin struct {
	URL   string `json:"url"`
	Label string `json:"label,omitempty"`
}

type WorkOrderParams struct {
	Title       string
	Description string
}

type WorkOrderStatusNote struct {
	WorkOrderID         string `json:"workOrderId"`
	Key                 string `json:"key"`
	Kind                string `json:"kind"`
	Headline            string `json:"headline"`
	Body                string `json:"body,omitempty"`
	CtaLabel            string `json:"ctaLabel,omitempty"`
	CtaURL              string `json:"ctaUrl,omitempty"`
	ShowOnlyWhenWaiting bool   `json:"showOnlyWhenWaiting,omitempty"`
}