core

type Action struct {
	Name           string
	Description    string
	UserAccessible bool
	Parameters     []configuration.Field
}

type ActionContext struct {
	Name            string
	Configuration   any
	Parameters      map[string]any
	Logger          *log.Entry
	HTTP            HTTPContext
	Metadata        MetadataContext
	ExecutionState  ExecutionStateContext
	Auth            AuthContext
	Requests        RequestContext
	AppInstallation AppInstallationContext
	Notifications   NotificationContext
}

type AppComponent interface {

	/*
	 * AppComponent inherits all the methods from Component interface,
	 * and adds a couple more, which are only applicable to app components.
	 */
	Component

	OnAppMessage(ctx AppMessageContext) error
}

type AppInstallationContext interface {

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

	//
	// Control the state of the app installation
	//
	GetState() string
	SetState(state, stateDescription string)

	//
	// Control the browser action of the app installation
	//
	NewBrowserAction(action BrowserAction)
	RemoveBrowserAction()

	//
	// Control the secrets of the app installation
	//
	SetSecret(name string, value []byte) error
	GetSecrets() ([]InstallationSecret, error)

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

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

	/*
	 * Schedule a sync call for the app installation.
	 */
	ScheduleResync(interval time.Duration) error

	/*
	 * List app installation subscriptions from nodes.
	 */
	ListSubscriptions() ([]AppSubscriptionContext, error)
}

type AppMessageContext struct {
	Message         any
	Configuration   any
	Logger          *logrus.Entry
	AppInstallation AppInstallationContext
	Events          EventContext
}

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

type AppTrigger interface {

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

	OnAppMessage(ctx AppMessageContext) error
}

type Application interface {
	/*
	 * The name of the application.
	 */
	Name() string

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

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

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

	/*
	 * Markdown-formatted instructions shown in the installation modal.
	 */
	InstallationInstructions() string

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

	/*
	 * The list of components exposed by the application.
	 */
	Components() []Component

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

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

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

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

	/*
	 * Used to compare webhook configurations.
	 * If the configuration is the same,
	 * the system will reuse the existing webhook.
	 */
	CompareWebhookConfig(a, b any) (bool, error)

	/*
	 * Set up webhooks through the app installation, in the external system.
	 * This is called by the webhook provisioner, for pending webhook records.
	 */
	SetupWebhook(ctx SetupWebhookContext) (any, error)

	/*
	 * Delete webhooks through the app installation, in the external system.
	 * This is called by the webhook cleanup worker, for webhook records that were deleted.
	 */
	CleanupWebhook(ctx CleanupWebhookContext) error
}

type ApplicationResource struct {
	Type string
	Name string
	ID   string
}

type AuthContext interface {
	AuthenticatedUser() *User
	GetUser(id uuid.UUID) (*User, 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 CleanupWebhookContext struct {
	HTTP            HTTPContext
	Webhook         WebhookContext
	AppInstallation AppInstallationContext
}

type Component 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

	/*
	 * 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 HandleAction().
	 */
	Execute(ctx ExecutionContext) error

	/*
	 * Allows components to define custom actions
	 * that can be called on specific executions of the component.
	 */
	Actions() []Action

	/*
	 * Execution a custom action - defined in Actions() -
	 * on a specific execution of the component.
	 */
	HandleAction(ctx ActionContext) error

	/*
	 * Handler for webhooks.
	 */
	HandleWebhook(ctx WebhookRequestContext) (int, 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
}

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

type ExecutionContext struct {
	ID              uuid.UUID
	WorkflowID      string
	OrganizationID  string
	NodeID          string
	SourceNodeID    string
	BaseURL         string
	Data            any
	Configuration   any
	ExpressionEnv   func(expression string) (map[string]any, error)
	Logger          *log.Entry
	HTTP            HTTPContext
	Metadata        MetadataContext
	NodeMetadata    MetadataContext
	ExecutionState  ExecutionStateContext
	Requests        RequestContext
	Auth            AuthContext
	AppInstallation AppInstallationContext
	Notifications   NotificationContext
}

type ExecutionStateContext interface {
	IsFinished() bool
	SetKV(key, value 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 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
	AppInstallation AppInstallationContext
}

type InstallationSecret struct {
	Name  string
	Value []byte
}

type ListResourcesContext struct {
	Logger          *logrus.Entry
	HTTP            HTTPContext
	AppInstallation AppInstallationContext
}

type MetadataContext interface {
	Get() any
	Set(any) error
}

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

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

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
	ExpressionEnv func(expression string) (map[string]any, error)

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

	//
	// CountDistinctIncomingSources returns the number of distinct upstream
	// source nodes connected to this node (ignoring multiple channels from the
	// same source)
	//
	CountDistinctIncomingSources func() (int, error)
}

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 SetupContext struct {
	Logger          *log.Entry
	Configuration   any
	HTTP            HTTPContext
	Metadata        MetadataContext
	Requests        RequestContext
	Auth            AuthContext
	AppInstallation AppInstallationContext
}

type SetupWebhookContext struct {
	HTTP            HTTPContext
	Webhook         WebhookContext
	Logger          *logrus.Entry
	AppInstallation AppInstallationContext
}

type SyncContext struct {
	Configuration   any
	BaseURL         string
	WebhooksBaseURL string
	OrganizationID  string
	InstallationID  string
	HTTP            HTTPContext
	AppInstallation AppInstallationContext
}

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

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

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

	/*
	 * Allows triggers to define custom actions.
	 */
	Actions() []Action

	/*
	 * Execution a custom action - defined in Actions() for a trigger.
	 */
	HandleAction(ctx TriggerActionContext) (map[string]any, error)
}

type TriggerActionContext struct {
	Name            string
	Parameters      map[string]any
	Configuration   any
	Logger          *log.Entry
	HTTP            HTTPContext
	Metadata        MetadataContext
	Requests        RequestContext
	Events          EventContext
	Webhook         NodeWebhookContext
	AppInstallation AppInstallationContext
}

type TriggerContext struct {
	Logger          *log.Entry
	Configuration   any
	HTTP            HTTPContext
	Metadata        MetadataContext
	Requests        RequestContext
	Events          EventContext
	Webhook         NodeWebhookContext
	AppInstallation AppInstallationContext
}

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 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
	Webhook       NodeWebhookContext
	Events        EventContext

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

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
}