workflows

type ApprovalActionParams struct {
	// TargetedActionParams identifies the approval recipients
	TargetedActionParams
	// Required defaults to true when omitted
	Required *bool `json:"required"`
	// Label is an optional display label for the approval action
	Label string `json:"label"`
	// RequiredCount sets a quorum threshold (number of approvals needed) for this action
	RequiredCount int `json:"required_count"`
	// Fields lists the approval-gated fields for domain derivation
	Fields []string `json:"fields,omitempty"`
}

type AssignmentContextBuilder func(ctx context.Context, client *generated.Client, instanceID string) (map[string]any, error)

type CELConfig struct {
	// Timeout is the maximum duration allowed for evaluating a CEL expression
	Timeout time.Duration `json:"timeout" koanf:"timeout" default:"100ms"`
	// CostLimit caps the runtime cost of CEL evaluation, 0 disables the limit
	CostLimit uint64 `json:"costlimit" koanf:"costlimit" default:"0"`
	// InterruptCheckFrequency controls how often CEL checks for interrupts during comprehensions
	InterruptCheckFrequency uint `json:"interruptcheckfrequency" koanf:"interruptcheckfrequency" default:"100"`
	// ParserRecursionLimit caps the parser recursion depth, 0 uses CEL defaults
	ParserRecursionLimit int `json:"parserrecursionlimit" koanf:"parserrecursionlimit" default:"250"`
	// ParserExpressionSizeLimit caps expression size (code points), 0 uses CEL defaults
	ParserExpressionSizeLimit int `json:"parserexpressionsizelimit" koanf:"parserexpressionsizelimit" default:"100000"`
	// ComprehensionNestingLimit caps nested comprehensions, 0 disables the check
	ComprehensionNestingLimit int `json:"comprehensionnestinglimit" koanf:"comprehensionnestinglimit" default:"0"`
	// ExtendedValidations enables extra AST validations (regex, duration, timestamps, homogeneous aggregates)
	ExtendedValidations bool `json:"extendedvalidations" koanf:"extendedvalidations" default:"true"`
	// OptionalTypes enables CEL optional types and optional field syntax
	OptionalTypes bool `json:"optionaltypes" koanf:"optionaltypes" default:"false"`
	// IdentifierEscapeSyntax enables backtick escaped identifiers
	IdentifierEscapeSyntax bool `json:"identifierescapesyntax" koanf:"identifierescapesyntax" default:"false"`
	// CrossTypeNumericComparisons enables comparisons across numeric types
	CrossTypeNumericComparisons bool `json:"crosstypenumericcomparisons" koanf:"crosstypenumericcomparisons" default:"false"`
	// MacroCallTracking records macro calls in AST source info for debugging
	MacroCallTracking bool `json:"macrocalltracking" koanf:"macrocalltracking" default:"false"`
	// EvalOptimize enables evaluation-time optimizations for repeated program runs
	EvalOptimize bool `json:"evaloptimize" koanf:"evaloptimize" default:"true"`
	// TrackState enables evaluation state tracking for debugging
	TrackState bool `json:"trackstate" koanf:"trackstate" default:"false"`
}

type CELContextBuilder func(obj *Object, changedFields []string, changedEdges []string, addedIDs, removedIDs map[string][]string, eventType, userID string) map[string]any

type Config struct {
	// Enabled determines if the workflows engine is enabled
	Enabled bool `json:"enabled" koanf:"enabled" default:"false"`
	// CEL contains configuration for CEL evaluation and validation
	CEL CELConfig `json:"cel" koanf:"cel"`
}

type ConfigOpts func(*Config)

type DomainChanges struct {
	// DomainKey is the derived key for the approval field set
	DomainKey string
	// Fields lists the approval fields included in the domain
	Fields []string
	// Changes is the subset of proposed changes for the domain
	Changes map[string]any
}

type EmitFailureDetails struct {
	// Topic is the soiree topic name
	Topic string `json:"topic"`
	// EventID is the idempotency key when available
	EventID string `json:"event_id,omitempty"`
	// Payload is the original event payload JSON
	Payload json.RawMessage `json:"payload,omitempty"`
	// Attempts is the number of emit attempts recorded
	Attempts int `json:"attempts"`
	// LastError is the most recent enqueue error
	LastError string `json:"last_error,omitempty"`
	// OriginalEventType is the workflow event type that failed
	OriginalEventType enums.WorkflowEventType `json:"original_event_type"`
	// ActionKey is the workflow action key when available
	ActionKey string `json:"action_key,omitempty"`
	// ActionIndex is the workflow action index when available
	ActionIndex int `json:"action_index"`
	// ObjectID is the workflow object id
	ObjectID string `json:"object_id,omitempty"`
	// ObjectType is the workflow object type
	ObjectType enums.WorkflowObjectType `json:"object_type,omitempty"`
}

type EmitFailureMeta struct {
	// EventType is the workflow event type associated with the emit
	EventType enums.WorkflowEventType
	// ActionKey is the workflow action key when available
	ActionKey string
	// ActionIndex is the workflow action index when available
	ActionIndex int
	// ObjectID is the target object id
	ObjectID string
	// ObjectType is the target object type
	ObjectType enums.WorkflowObjectType
}

type EmitReceipt struct {
	// EventID is the event idempotency key when assigned
	EventID string
	// Enqueued reports whether the event was enqueued
	Enqueued bool
	// Err is the enqueue error when present
	Err error
}

type FieldUpdateActionParams struct {
	// Updates maps field names to new values
	Updates map[string]any `json:"updates"`
}

type IntegrationActionParams struct {
	// Integration is the integration identifier for the operation
	Integration string `json:"integration"`
	// Provider overrides the integration identifier when set
	Provider string `json:"provider"`
	// Operation is the integration operation name
	Operation string `json:"operation"`
	// Config holds the integration-specific configuration payload
	Config map[string]any `json:"config"`

	// TimeoutMS overrides the operation timeout in milliseconds
	TimeoutMS int `json:"timeout_ms"`
	// Retries overrides the retry count when non-zero
	Retries int `json:"retries"`
	// Force requests a refresh for the provider
	Force bool `json:"force_refresh"`
	// ClientForce requests a client-side refresh for the provider
	ClientForce bool `json:"client_force"`
}

type NotificationActionParams struct {
	// TargetedActionParams identifies the notification recipients
	TargetedActionParams
	// Channels selects notification delivery channels
	Channels []enums.Channel `json:"channels"`
	// Topic sets an optional notification topic
	Topic string `json:"topic"`
	// Title is the notification title
	Title string `json:"title"`
	// Body is the notification body
	Body string `json:"body"`
	// Data is an optional payload merged into the notification data
	Data map[string]any `json:"data"`
}

type Object struct {
	// ID is the workflow object identifier.
	ID string
	// Type is the workflow object type.
	Type enums.WorkflowObjectType
	// Node is the concrete ent entity when available.
	Node any
}

type ObjectRefQueryBuilder func(*generated.WorkflowObjectRefQuery, *Object) (*generated.WorkflowObjectRefQuery, bool)

type TargetConfig struct {
	// Type selects how targets are resolved.
	Type enums.WorkflowTargetType `json:"type"`
	// ID identifies the target resource for static targets.
	ID string `json:"id,omitempty"`
	// ResolverKey names the resolver used for dynamic targets.
	ResolverKey string `json:"resolver_key,omitempty"`
}

type TargetedActionParams struct {
	// Targets identifies users, groups, roles, or resolvers to receive the action
	Targets []TargetConfig `json:"targets"`
}

type WebhookActionParams struct {
	// URL is the webhook endpoint
	URL string `json:"url"`
	// Method is the HTTP method for the webhook request
	Method string `json:"method"`
	// Headers are additional HTTP headers for the webhook request
	Headers map[string]string `json:"headers"`
	// Payload is merged into the base webhook payload
	Payload map[string]any `json:"payload"`
	// TimeoutMS overrides the webhook timeout in milliseconds
	TimeoutMS int `json:"timeout_ms"`
	// Secret signs the webhook payload if provided
	Secret string `json:"secret"`
	// Retries overrides the retry count when non-zero
	Retries int `json:"retries"`

	// Optional override for the idempotency key header
	IdempotencyKey string `json:"idempotency_key"`
}

type WorkflowBypassContextKey struct{}

type WorkflowCreationError struct {
	// Stage is the creation stage that failed
	Stage WorkflowCreationStage
	// Err is the underlying error
	Err error
}

type WorkflowCreationStage string

type WorkflowInstanceBuilderParams struct {
	// WorkflowDefinitionID is the definition id for the instance
	WorkflowDefinitionID string
	// DefinitionSnapshot is the snapshot of the workflow definition
	DefinitionSnapshot models.WorkflowDefinitionDocument
	// State is the initial workflow instance state
	State enums.WorkflowInstanceState
	// Context is the workflow instance context payload
	Context models.WorkflowInstanceContext
	// OwnerID is the organization owner id
	OwnerID string
	// ObjectType is the workflow object type
	ObjectType enums.WorkflowObjectType
	// ObjectID is the workflow object id
	ObjectID string
}