operations

type DispatchRequest struct {
	// IntegrationID is the target integration identifier; required on the customer path, empty on the runtime path
	IntegrationID string
	// DefinitionID is the definition identifier carried as metadata on the runtime path
	DefinitionID string
	// OwnerID is the owning organization carried on the runtime path; derived from the DB record for customer dispatch
	OwnerID string
	// Operation is the definition-local operation identifier
	Operation string
	// Config is the operation configuration payload
	Config json.RawMessage
	// ForceClientRebuild requests client cache bypass
	ForceClientRebuild bool
	// RunType is the integration run type recorded for the dispatch
	RunType enums.IntegrationRunType
	// Workflow carries optional workflow linkage for workflow-triggered operations
	Workflow *types.WorkflowMeta
	// ScheduledAt defers execution until the specified time; nil means immediate
	ScheduledAt *time.Time
	// Runtime signals that this dispatch should use the runtime provider path
	Runtime bool
}

type DispatchResult struct {
	// RunID is the persisted run identifier
	RunID string
	// EventID is the emitted Gala event identifier
	EventID string
	// Status is the run status at dispatch time
	Status enums.IntegrationRunStatus
}

type Envelope struct {
	types.ExecutionMetadata
	// Config is the operation configuration payload
	Config json.RawMessage `json:"config,omitempty"`
	// ForceClientRebuild requests client cache bypass
	ForceClientRebuild bool `json:"forceClientRebuild,omitempty"`
}

type IngestContext struct {
	// Registry is the integration definition registry used to resolve mappings and definitions
	Registry *registry.Registry
	// DB is the ent client used for persistence
	DB *ent.Client
	// Runtime is the Gala instance used for async emit; nil on the synchronous persist path
	Runtime *gala.Gala
	// Integration is the integration record being ingested into
	Integration *ent.Integration
}

type IngestOptions struct {
	// DirectorySyncRunID groups all directory-related ingest records from one sync batch
	DirectorySyncRunID string
	// SkipDirectorySyncRunFinalization instructs the processor not to finalize the directory sync run after processing
	SkipDirectorySyncRunFinalization bool
	// Source identifies the mechanism that produced the ingest data (e.g. webhook, poll, manual)
	Source integrationgenerated.IntegrationIngestSource
	// RunID is a caller-supplied correlation identifier for the overall operation run
	RunID string
	// Webhook is the webhook name or identifier that triggered this ingest
	Webhook string
	// WebhookEvent is the event type reported by the webhook provider
	WebhookEvent string
	// DeliveryID is the provider-assigned delivery identifier; used for deduplication
	DeliveryID string
	// WorkflowMeta carries workflow instance context
	WorkflowMeta *types.WorkflowMeta
}

type ReconcileEnvelope struct {
	types.ExecutionMetadata
	// Schedule is the adaptive scheduling state carried across cycles
	Schedule gala.ScheduleState `json:"schedule"`
}

type ReconcileHandler func(context.Context, ReconcileEnvelope) (int, error)

type RecurringCampaignEnvelope struct {
	// Schedule is the adaptive scheduling state carried across polling cycles
	Schedule gala.ScheduleState `json:"schedule"`
}

type RecurringCampaignHandler func(context.Context, RecurringCampaignEnvelope) (int, error)

type RunResult struct {
	// Status is the terminal run status
	Status enums.IntegrationRunStatus
	// Summary is the optional summary text stored on the run
	Summary string
	// Error is the optional terminal error text stored on the run
	Error string
	// Metrics is the structured metrics payload stored on the run
	Metrics map[string]any
}

type ScheduledListenerConfig[T any] struct {
	// Runtime is the Gala instance to register on
	Runtime *gala.Gala
	// Topic is the Gala topic name
	Topic gala.TopicName
	// Name is the stable listener name
	Name string
	// Schedule controls adaptive interval computation
	Schedule gala.Schedule
	// Handle is the handler invoked each cycle, returning the delta for scheduling
	Handle func(context.Context, T) (int, error)
	// State extracts the ScheduleState from the envelope
	State func(T) gala.ScheduleState
	// Wrap builds a new envelope carrying the updated ScheduleState
	Wrap func(T, gala.ScheduleState) T
	// PrepareEmit optionally enriches the context and headers before re-emitting
	PrepareEmit func(context.Context, T) (context.Context, gala.Headers)
	// ShouldCancel optionally classifies an execution error; when it returns
	// true the cycle is cancelled immediately without scheduling a retry
	ShouldCancel func(context.Context, T, error) bool
	// ScheduleOverride optionally returns a per-envelope schedule that
	// overrides the default; returning nil falls back to the config-level Schedule
	ScheduleOverride func(T) *gala.Schedule
}

type WebhookEnvelope struct {
	types.ExecutionMetadata
	// Payload is the raw webhook request body
	Payload json.RawMessage `json:"payload"`
	// Headers contains the inbound HTTP request headers
	Headers map[string]string `json:"headers,omitempty"`
}