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
	MetadataContext        MetadataContext
	ExecutionStateContext  ExecutionStateContext
	AuthContext            AuthContext
	RequestContext         RequestContext
	IntegrationContext     IntegrationContext
	AppInstallationContext AppInstallationContext
}

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

	/*
	 * Schedule a sync call for the app installation.
	 */
	ScheduleResync(interval time.Duration) 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

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

	/*
	 * 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 AppInstallationContext, options WebhookOptions) (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 AppInstallationContext, options WebhookOptions) error
}

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

	/*
	 * 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
	Data                   any
	Configuration          any
	Logger                 *log.Entry
	MetadataContext        MetadataContext
	NodeMetadataContext    MetadataContext
	ExecutionStateContext  ExecutionStateContext
	RequestContext         RequestContext
	AuthContext            AuthContext
	IntegrationContext     IntegrationContext
	AppInstallationContext AppInstallationContext
}

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 HTTPRequestContext struct {
	Logger          *logrus.Entry
	Request         *http.Request
	Response        http.ResponseWriter
	OrganizationID  string
	BaseURL         string
	WebhooksBaseURL string
	AppInstallation AppInstallationContext
}

type InstallationSecret struct {
	Name  string
	Value []byte
}

type IntegrationContext interface {
	GetIntegration(ID string) (integrations.ResourceManager, error)
}

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

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

	//
	// 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
	MetadataContext        MetadataContext
	RequestContext         RequestContext
	AuthContext            AuthContext
	IntegrationContext     IntegrationContext
	AppInstallationContext AppInstallationContext
}

type SyncContext struct {
	Configuration   any
	BaseURL         string
	WebhooksBaseURL string
	OrganizationID  string
	InstallationID  string
	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

	/*
	 * 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
	MetadataContext        MetadataContext
	RequestContext         RequestContext
	EventContext           EventContext
	WebhookContext         WebhookContext
	AppInstallationContext AppInstallationContext
}

type TriggerContext struct {
	Logger                 *log.Entry
	Configuration          any
	MetadataContext        MetadataContext
	RequestContext         RequestContext
	EventContext           EventContext
	WebhookContext         WebhookContext
	IntegrationContext     IntegrationContext
	AppInstallationContext 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 {
	Setup(options *WebhookSetupOptions) (string, error)
	GetSecret() ([]byte, error)
	ResetSecret() ([]byte, []byte, error)
	GetBaseURL() string
}

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
	WebhookContext WebhookContext
	EventContext   EventContext

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

type WebhookSetupOptions struct {
	IntegrationID     *uuid.UUID
	AppInstallationID *uuid.UUID
	Resource          integrations.Resource
	Configuration     any
}

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
}