sdk

type Action interface {
	// Metadata returns metadata about the action
	Metadata() ActionMetadata

	// Properties returns the schema for the action's input configuration
	Properties() *smartform.FormSchema

	// Auth returns the authentication requirements for the action
	Auth() *core.AuthMetadata

	// Perform executes the action with the given context and input
	Perform(ctx context.PerformContext) (core.JSON, error)
}

type ActionDefinition struct {
	// Name is the unique identifier for this action within its integration
	Name string `json:"id"`

	// DisplayName is the human-readable name of the action
	DisplayName string `json:"displayName"`

	// Description provides details about the action's purpose
	Description string `json:"description"`

	// HelpText provides additional guidance for configuring the action
	HelpText string `json:"helpText,omitempty"`

	// Icon is a URL or base64-encoded image for the action icon
	Icon string `json:"icon,omitempty"`

	// Type specifies the action type (e.g., ACTION, BRANCH, BOOLEAN)
	Type core.ActionType `json:"type"`

	// Auth represents the authentication configuration required to perform the action, encapsulated in core.AuthMetadata.
	Auth *core.AuthMetadata

	// Documentation provides comprehensive usage instructions
	Documentation string `json:"documentation,omitempty"`

	// SampleOutput contains an example of the action's output
	SampleOutput core.JSON `json:"sampleOutput,omitempty"`

	Properties *smartform.FormSchema

	// Tags are searchable labels for the action
	Tags []string `json:"tags,omitempty"`

	// Implementation specifies the action implementation logic or function to be executed.
	Implementation Action
}

type ActionError struct {
	// Code is a machine-readable error code
	Code string `json:"code"`

	// Message is a human-readable error message
	Message string `json:"message"`

	// Retryable indicates if the error is temporary and the action can be retried
	Retryable bool `json:"retryable"`

	// Details contains additional context for the error
	Details map[string]interface{} `json:"details,omitempty"`
}

type ActionFactory interface {
	// CreateAction creates an action instance based on type
	CreateAction(actionType core.ActionType, config map[string]interface{}) (Action, error)

	// RegisterActionCreator registers a function to create a specific action type
	RegisterActionCreator(actionType core.ActionType, creator func(config map[string]interface{}) (Action, error)) error

	// ListSupportedActionTypes returns all action types supported by this factory
	ListSupportedActionTypes() []core.ActionType
}

type ActionMetadata struct {
	// ID is the unique identifier for this action within its integration
	ID string `json:"id"`

	// DisplayName is the human-readable name of the action
	DisplayName string `json:"displayName"`

	// Description provides details about the action's purpose
	Description string `json:"description"`

	// HelpText provides additional guidance for configuring the action
	HelpText string `json:"helpText,omitempty"`

	// Icon is a URL or base64-encoded image for the action icon
	Icon string `json:"icon,omitempty"`

	// Type specifies the action type (e.g., ACTION, BRANCH, BOOLEAN)
	Type core.ActionType `json:"type"`

	// Documentation provides comprehensive usage instructions
	Documentation string `json:"documentation,omitempty"`

	// SampleOutput contains an example of the action's output
	SampleOutput core.JSON `json:"sampleOutput,omitempty"`

	// Tags are searchable labels for the action
	Tags []string `json:"tags,omitempty"`

	// Category provides a categorization for this action
	Category string `json:"category,omitempty"`

	// Settings returns action-specific settings
	Settings core.ActionSettings
}

type ActionRegistry interface {
	// RegisterAction adds an action to the registry
	RegisterAction(integrationID string, action Action) error

	// UnregisterAction removes an action from the registry
	UnregisterAction(integrationID string, actionID string) error

	// GetAction retrieves an action by integration ID and action ID
	GetAction(integrationID string, actionID string) (Action, error)

	// ListActions returns all registered actions
	ListActions() map[string][]Action

	// ListActionsByType returns actions of a specific type
	ListActionsByType(actionType core.ActionType) []Action

	// ListActionsByIntegration returns all actions for a specific integration
	ListActionsByIntegration(integrationID string) []Action

	// ListActionsByCategory returns actions in a specific category
	ListActionsByCategory(category string) []Action

	// SearchActions searches for actions matching criteria
	SearchActions(query string, filters map[string]interface{}) []Action
}

type Auth interface {
	// Initialize starts an authentication flow
	Initialize(ctx context.Context, request AuthRequest) (*AuthResponse, error)

	// CompleteOAuth finishes an OAuth flow with a code from the OAuth provider
	CompleteOAuth(ctx context.Context, connectionID xid.ID, code string, state string) (*AuthResponse, error)

	// Refresh renews an authentication token
	Refresh(ctx context.Context, connectionID xid.ID) (*AuthResponse, error)

	// Revoke explicitly revokes an authentication connection
	Revoke(ctx context.Context, connectionID xid.ID) error

	// Validate checks if an authentication connection is valid
	Validate(ctx context.Context, connectionID xid.ID) (*AuthResponse, error)

	// GetConnection retrieves authentication connection details
	GetConnection(ctx context.Context, connectionID xid.ID) (*AuthResponse, error)

	// ListConnections retrieves all authentication connections for a project
	ListConnections(ctx context.Context, projectID xid.ID) ([]AuthResponse, error)

	// GetToken retrieves an OAuth token for use in API calls
	GetToken(ctx context.Context, connectionID xid.ID) (*oauth2.Token, error)

	// GetAuthContext retrieves the auth context for use in integration operations
	GetAuthContext(ctx context.Context, connectionID xid.ID) (*wakcontext.AuthContext, error)

	// CreateAuthenticatedClient creates an HTTP client with authentication credentials
	CreateAuthenticatedClient(ctx context.Context, connectionID xid.ID) (*http.Client, error)
}

type AuthConnectionStatus string

type AuthRequest struct {
	// IntegrationID is the identifier for the integration requiring authentication
	IntegrationID string `json:"integrationId"`

	// ProjectID is the identifier for the project this authentication belongs to
	ProjectID xid.ID `json:"projectId"`

	// UserID is the identifier for the user initiating the authentication
	UserID xid.ID `json:"userId,omitempty"`

	// Type specifies the authentication method to use
	Type core.AuthType `json:"type"`

	// ConnectionName is a user-defined name for this connection
	ConnectionName string `json:"connectionName"`

	// Credentials contains authentication credentials (for non-OAuth flows)
	Credentials map[string]interface{} `json:"credentials,omitempty"`

	// Metadata contains additional information about this authentication
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// RedirectURL is where to redirect after OAuth authentication
	RedirectURL string `json:"redirectUrl,omitempty"`

	// Scopes contains the OAuth scopes to request
	Scopes []string `json:"scopes,omitempty"`
}

type AuthResponse struct {
	// ConnectionID is the unique identifier for this authentication connection
	ConnectionID xid.ID `json:"connectionId"`

	// Status indicates the current status of this connection
	Status AuthConnectionStatus `json:"status"`

	// Type indicates the authentication method used
	Type core.AuthType `json:"type"`

	// ExpiresAt indicates when this authentication expires (if applicable)
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`

	// Message contains additional information about the authentication result
	Message string `json:"message,omitempty"`

	// AuthorizationURL is the URL to redirect to for OAuth flows
	AuthorizationURL string `json:"authorizationUrl,omitempty"`

	// ConnectionDetails contains details about the connection (sanitized for display)
	ConnectionDetails map[string]interface{} `json:"connectionDetails,omitempty"`
}

type DynamicIntegrationLoader interface {
	// LoadIntegration loads an integration from a file or URL
	LoadIntegration(ctx context.Context, source string) (*IntegrationDefinition, error)

	// ValidateIntegration checks if an integration package is valid
	ValidateIntegration(ctx context.Context, source string) (bool, error)

	// GetIntegrationDefinition extracts metadata from an integration package
	GetIntegrationDefinition(ctx context.Context, source string) (*IntegrationDefinition, error)

	// GetIntegrationMetadata extracts metadata from an integration package
	GetIntegrationMetadata(ctx context.Context, source string) (*IntegrationMetadata, error)

	// ExtractIntegration extracts and validates integration data from the given path and returns its identifier or an error.
	ExtractIntegration(ctx context.Context, path string) (string, error)

	// RegisterIntegration loads and registers an integration with the registry
	RegisterIntegration(ctx context.Context, source string, registry IntegrationRegistry) error
}

type Integration interface {
	// Metadata returns metadata about the integration
	Metadata() IntegrationMetadata

	// Auth returns the authentication requirements for the integration
	Auth() *core.AuthMetadata

	// Triggers returns all triggers provided by this integration
	Triggers() []Trigger

	// Actions returns all actions provided by this integration
	Actions() []Action
}

type IntegrationDefinition struct {
	ID            string                        `json:"id"`
	Name          string                        `json:"name"`
	DisplayName   string                        `json:"displayName"`
	Description   string                        `json:"description"`
	Version       string                        `json:"version"`
	Icon          string                        `json:"icon"`
	Actions       map[string]*ActionDefinition  `json:"actions"`
	Triggers      map[string]*TriggerDefinition `json:"triggers"`
	Auth          core.AuthMetadata             `json:"auth"`
	Metadata      IntegrationMetadata           `json:"metadata"`
	BuildMetadata core.IntegrationBuildMetadata `json:"buildMetadata"`
	Documentation string                        `json:"documentation,omitempty"`
	ReleaseNotes  string                        `json:"releaseNotes,omitempty"`
	Type          IntegrationType               `json:"type"`
	Categories    []string                      `json:"categories"`
	Tags          []string                      `json:"tags"`
	Authors       []string                      `json:"authors"`
	Website       *string                       `json:"website"`
	License       *string                       `json:"license"`
	Copyright     *string                       `json:"copyright"`
	LicenseURL    *string                       `json:"licenseUrl"`
	CopyrightURL  *string                       `json:"copyrightUrl"`
	Source        *string                       `json:"source"`

	Implementation Integration `json:"-"`
}

type IntegrationMetadata struct {
	// Name is the human-readable name of the integration
	Name string `json:"name" toml:"name" yaml:"name" validate:"required"`

	// Description provides details about the integration's purpose
	Description string `json:"description" toml:"description"  yaml:"description" validate:"required"`

	// Type categorizes the integration functionality
	Type IntegrationType `json:"type"`

	// Version is the semantic version of the integration
	Version string `json:"version" toml:"version" yaml:"version" validate:"required"`

	// Icon is a URL or base64-encoded image for the integration icon
	Icon string `json:"icon" toml:"icon" yaml:"icon" validate:"required"`

	// Publisher identifies who created the integration
	Authors []string `json:"authors" toml:"authors" yaml:"authors" validate:"required"`

	// Website is the URL to the integration's documentation or website
	Website string `json:"website" toml:"website" yaml:"website"`

	// Category provides a more specific categorization
	Categories []string `json:"categories" toml:"categories" yaml:"categories" validate:"required"`

	// Tags are searchable labels for the integration
	Tags []string `json:"tags,omitempty" toml:"tags,omitempty" yaml:"tags,omitempty"`

	// ReleaseNotes documents changes in this version
	ReleaseNotes string `json:"releaseNotes,omitempty"`

	// Documentation provides comprehensive usage instructions
	Documentation string `json:"documentation,omitempty"`
}

type IntegrationRegistry interface {
	// RegisterIntegration adds an integration to the registry
	RegisterIntegration(integration Integration) error

	// RegisterIntegrationDefinition adds an integration to the registry
	RegisterIntegrationDefinition(integration IntegrationDefinition) error

	// UnregisterIntegration removes an integration from the registry
	UnregisterIntegration(name string, version string) error

	// GetIntegration retrieves a specific version of an integration by its name and version from the registry.
	GetIntegration(ctx context.Context, name string, version string) (Integration, error)

	// GetIntegrationDefinition retrieves a specific version of an integration by its name and version from the registry.
	GetIntegrationDefinition(ctx context.Context, name string, version string) (*IntegrationDefinition, error)

	// GetLatestIntegration retrieves the latest version of an integration
	GetLatestIntegration(ctx context.Context, name string) (*IntegrationDefinition, error)

	// ListIntegrations returns all registered integrations
	ListIntegrations() []*IntegrationDefinition

	// ListIntegrationsByType returns integrations of a specific type
	ListIntegrationsByType(integrationType IntegrationType) []*IntegrationDefinition

	// ListIntegrationVersions returns all versions of an integration
	ListIntegrationVersions(ctx context.Context, name string) ([]*IntegrationDefinition, error)

	// GetIntegrationMetadata retrieves metadata for a specific integration given its name and version. It returns the metadata or an error.
	GetIntegrationMetadata(ctx context.Context, name string, version string) (*IntegrationMetadata, error)

	RegisterActionDefinition(
		ctx context.Context,
		integrationName string,
		version string,
		actionID string,
		action ActionDefinition,
	) error

	RegisterTriggerDefinition(
		ctx context.Context,
		integrationName string,
		version string,
		triggerID string,
		trigger TriggerDefinition,
	) error

	RegisterAction(
		ctx context.Context,
		integrationName string,
		version string,
		actionID string,
		action Action,
	) error

	RegisterTrigger(
		ctx context.Context,
		integrationName string,
		version string,
		triggerID string,
		trigger Trigger,
	) error

	// GetAction retrieves an action by integration ID and action ID
	GetAction(integrationID, version, actionID string) (*ActionDefinition, error)

	// GetTrigger retrieves a trigger by integration ID and trigger ID
	GetTrigger(integrationID, version, actionID string) (*TriggerDefinition, error)

	// ListActions returns all actions for an integration version
	ListActions(
		ctx context.Context,
		integrationName string,
		version string,
	) (map[string]*ActionDefinition, error)

	// ListTriggers returns all triggers for an integration version
	ListTriggers(
		ctx context.Context,
		integrationName string,
		version string,
	) (map[string]*TriggerDefinition, error)

	// ListAllActions returns all registered actions across all integrations
	ListAllActions(ctx context.Context) map[string]map[string]map[string]*ActionDefinition

	// ListAllTriggers returns all registered triggers across all integrations
	ListAllTriggers(ctx context.Context) map[string]map[string]map[string]*TriggerDefinition

	// Initialize initializes all registered integrations
	Initialize(ctx context.Context) error

	// Shutdown performs cleanup for all registered integrations
	Shutdown(ctx context.Context) error
}

type IntegrationType string

type Trigger interface {
	// Metadata returns metadata about the trigger
	Metadata() TriggerMetadata

	// Props returns the schema for the trigger's input configuration
	Props() *smartform.FormSchema

	// Auth returns the authentication requirements for the trigger
	Auth() *core.AuthMetadata

	// Start prepares and activates the trigger (e.g., start polling, event listening, cron schedules)
	Start(ctx context.LifecycleContext) error

	// Stop gracefully stops or disables the trigger
	Stop(ctx context.LifecycleContext) error

	// Execute handles the trigger's action when manually invoked with an input schema
	Execute(ctx context.ExecuteContext) (core.JSON, error)
}

type TriggerDefinition struct {
	// ID is the unique identifier for this trigger within its integration
	Name string `json:"name"`

	// DisplayName is the human-readable name of the trigger
	DisplayName string `json:"displayName"`

	// Description provides details about the trigger's purpose
	Description string `json:"description"`

	// HelpText provides additional guidance for configuring the trigger
	HelpText string `json:"helpText,omitempty"`

	// Icon is a URL or base64-encoded image for the trigger icon
	Icon string `json:"icon,omitempty"`

	// Type specifies the trigger type (e.g., POLLING, WEBHOOK)
	Type core.TriggerType `json:"type"`

	// Auth represents the authentication configuration required to perform the action, encapsulated in core.AuthMetadata.
	Auth *core.AuthMetadata

	// Documentation provides comprehensive usage instructions
	Documentation string `json:"documentation,omitempty"`

	// SampleOutput contains an example of the trigger's output
	SampleOutput core.JSON `json:"sampleOutput,omitempty"`

	// Properties defines the schema for additional configuration required for the trigger in the form of a smartform.
	Properties *smartform.FormSchema

	// Implementation specifies the action implementation logic or function to be executed.
	Implementation Trigger
}

type TriggerFactory interface {
	// CreateTrigger creates a trigger instance based on type
	CreateTrigger(triggerType core.TriggerType, config map[string]interface{}) (Trigger, error)

	// RegisterTriggerCreator registers a function to create a specific trigger type
	RegisterTriggerCreator(triggerType core.TriggerType, creator func(config map[string]interface{}) (Trigger, error)) error

	// ListSupportedTriggerTypes returns all trigger types supported by this factory
	ListSupportedTriggerTypes() []core.TriggerType
}

type TriggerMetadata struct {
	// ID is the unique identifier for this trigger within its integration
	ID string `json:"id"`

	// DisplayName is the human-readable name of the trigger
	DisplayName string `json:"displayName"`

	// Description provides details about the trigger's purpose
	Description string `json:"description"`

	// HelpText provides additional guidance for configuring the trigger
	HelpText string `json:"helpText,omitempty"`

	// Icon is a URL or base64-encoded image for the trigger icon
	Icon string `json:"icon,omitempty"`

	// Type specifies the trigger type (e.g., POLLING, WEBHOOK)
	Type core.TriggerType `json:"type"`

	// Documentation provides comprehensive usage instructions
	Documentation string `json:"documentation,omitempty"`

	// SampleOutput contains an example of the trigger's output
	SampleOutput core.JSON `json:"sampleOutput,omitempty"`

	// Criteria returns additional trigger criteria configuration
	Criteria *core.TriggerSettings
}

type TriggerRegistry interface {
	// RegisterTrigger adds a trigger to the registry
	RegisterTrigger(integrationID string, trigger Trigger) error

	// UnregisterTrigger removes a trigger from the registry
	UnregisterTrigger(integrationID string, triggerID string) error

	// GetTrigger retrieves a trigger by integration ID and trigger ID
	GetTrigger(integrationID string, triggerID string) (Trigger, error)

	// ListTriggers returns all registered triggers
	ListTriggers() map[string][]Trigger

	// ListTriggersByType returns triggers of a specific type
	ListTriggersByType(triggerType core.TriggerType) []Trigger

	// ListTriggersByIntegration returns all triggers for a specific integration
	ListTriggersByIntegration(integrationID string) []Trigger
}