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

	/*
	 * 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)

	/*
	 * 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
	Notifications  NotificationContext
	Secrets        SecretsContext
}

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 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 Configurable interface {
	Configuration() []configuration.Field
}

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

type ExecutionContext struct {
	ID             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
	Notifications  NotificationContext
	Secrets        SecretsContext
	CanvasMemory   CanvasMemoryContext
	Webhook        NodeWebhookContext
	Expressions    ExpressionContext
}

type ExecutionStateContext interface {
	IsFinished() 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

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

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

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

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 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)

	/*
	 * 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
}

type IntegrationSecret struct {
	Name  string
	Value []byte
}

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

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 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 NodeWebhookContext interface {
	Setup() (string, error)
	GetSecret() ([]byte, error)
	SetSecret(secret []byte) error
	ResetSecret() ([]byte, []byte, error)
	GetBaseURL() string
}

type NotificationContext interface {
	Send(title, body, url, urlLabel string, receivers NotificationReceivers) error
	IsAvailable() bool
}

type NotificationReceivers struct {
	Emails []string
	Groups []string
	Roles  []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

	//
	// 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)

	//
	// DefaultProcessing performs the default processing for the queue item.
	// Convenience method to avoid boilerplate in components that just want default behavior,
	// where an execution is created and the item is dequeued.
	//
	DefaultProcessing func() (*uuid.UUID, 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 RedirectPrompt struct {
	URL      string
	Method   string
	FormData map[string]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 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)
}

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

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
	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
}

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 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
}

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
	WorkflowID    string
	NodeID        string
	Configuration any
	Metadata      MetadataWriter
	Logger        *log.Entry
	Webhook       NodeWebhookContext
	Events        EventContext
	Integration   IntegrationContext

	//
	// Return an execution context for a given execution,
	// through a referencing key-value pair.
	//
	FindExecutionByKV 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
}