messaging

type AgentChatRunData struct {
	AccountID         string `json:"account_id"`
	AgentDefinitionID string `json:"agent_definition_id"`
	ConversationID    string `json:"conversation_id"`
	TriggerMessageID  string `json:"trigger_message_id"`
	Message           string `json:"message"`
	// History is the recent thread context preceding the trigger, oldest-first, so the agent can follow the conversation instead of seeing only the triggering message. Role is from this agent's perspective: its own past replies are "assistant", everyone else is "user". Only set when starting a new run — a continued run already carries its own history.
	History []ChatHistoryMessage `json:"history,omitempty"`
	// ContinueRunID, when set, is the run to continue (the user replied directly to that run's message) instead of starting a new run. Empty means start a fresh run.
	ContinueRunID string `json:"continue_run_id,omitempty"`
}

type AgentContinueRunData struct {
	AgentRunID        string   `json:"agent_run_id"`
	AccountID         string   `json:"account_id"`
	Message           string   `json:"message"`
	ApprovedToolSlugs []string `json:"approved_tool_slugs,omitempty"`
	// ApproveAllPending, when true, approves every still-pending review-gated tool on the run (the "Approve all" control). It is the only way an empty ApprovedToolSlugs grants approval — set solely on an explicit approval with no specific slugs. A typed-message continuation or a retry leaves it false, so a blocked tool is never silently let through and re-prompts the next time it is called.
	ApproveAllPending bool `json:"approve_all_pending,omitempty"`
	// RejectedToolSlugs are the review-gated tools the human denied on this resume. The run continues; the runner answers each with a synthetic "denied by user" tool result so the agent proceeds without them.
	RejectedToolSlugs []string `json:"rejected_tool_slugs,omitempty"`
	// ApprovedToolCallIDs / RejectedToolCallIDs are per-call decisions: the tool_use_ids of individual blocked
	// calls the human approved/denied. Unlike the slug lists (which apply to every pending call of a slug),
	// these target one specific call, so two same-slug calls with different inputs are decided independently.
	ApprovedToolCallIDs []string `json:"approved_tool_call_ids,omitempty"`
	RejectedToolCallIDs []string `json:"rejected_tool_call_ids,omitempty"`
	ActorID             string   `json:"actor_id,omitempty"`
	ActorType           string   `json:"actor_type,omitempty"`
	ActorName           string   `json:"actor_name,omitempty"`
	// ReplyToMessageID threads this turn's reply under the message that triggered the continuation (the user's reply to the agent), so a chat thread keeps growing as one. Empty for non-chat continuations (e.g. the agent-run console).
	ReplyToMessageID string `json:"reply_to_message_id,omitempty"`
}

type AgentExecuteActionData struct {
	AgentActionID   string          `json:"agent_action_id"`
	ToolSlug        string          `json:"tool_slug"`
	ProposedPayload json.RawMessage `json:"proposed_payload"`
	AccountID       string          `json:"account_id"`
}

type AgentExecuteRunData struct {
	AgentRunID    string `json:"agent_run_id"`
	AgentConfigID string `json:"agent_config_id"`
	AccountID     string `json:"account_id"`
	TriggerType   string `json:"trigger_type"`
}

type AgentReplyData struct {
	AccountID      string `json:"account_id"`
	ConversationID string `json:"conversation_id"`
	AgentConfigID  string `json:"agent_config_id"`
	// AgentName is the agent definition's display name, carried so chat bell notifications can title themselves after the agent (name lives in agent-service, not notification-service).
	AgentName       string `json:"agent_name,omitempty"`
	AgentRunID      string `json:"agent_run_id"`
	Body            string `json:"body"`
	ClientMessageID string `json:"client_message_id"`
	// MessageID is the agent-generated message row id, shared by the start/patch/final messages of one streaming reply so they address the same record. Empty falls back to a service-generated id.
	MessageID string `json:"message_id,omitempty"`
	// Phase is "start" | "final" | "" (legacy single-shot create-and-complete).
	Phase string `json:"phase,omitempty"`
	// Failed marks a "final" reply that resolves an errored run (the body is the user-facing error).
	Failed bool `json:"failed,omitempty"`
	// ErrorCode is the machine-readable api-error code for a failed reply (e.g. "agent_spending_cap_reached"), carried onto the message so the client can react (e.g. prompt to raise the spending limit). Empty for non-cap or non-failed replies.
	ErrorCode string `json:"error_code,omitempty"`
	// ReplyToMessageID threads the reply under the message that triggered the run (a mention or keyword), so it renders as a reply. Empty for continuation turns (already in a reply thread).
	ReplyToMessageID string `json:"reply_to_message_id,omitempty"`
	// ApprovalEvent marks this as a tool-approval notice rather than an agent reply: the consumer posts it as a senderless system_event (Body = "{approver} approved {tools}") that renders as a timeline divider, not an agent bubble. AgentConfigID/AgentRunID are not required in this mode.
	ApprovalEvent bool `json:"approval_event,omitempty"`
}

type AgentReplyPatchData struct {
	AccountID      string `json:"account_id"`
	ConversationID string `json:"conversation_id"`
	MessageID      string `json:"message_id"`
	Body           string `json:"body"`
}

type AgentRunCompletedData struct {
	AgentRunID       string `json:"agent_run_id"`
	AccountID        string `json:"account_id"`
	BillingAccountID string `json:"billing_account_id"`
	InputTokens      int    `json:"input_tokens"`
	OutputTokens     int    `json:"output_tokens"`
	TotalTokens      int    `json:"total_tokens"`
	LLMProvider      string `json:"llm_provider"`
	LLMModel         string `json:"llm_model"`
}

type AgentRunStepData struct {
	AgentRunID string          `json:"agent_run_id"`
	AccountID  string          `json:"account_id"`
	EventID    string          `json:"event_id"`
	StepType   string          `json:"step_type"`
	Title      string          `json:"title"`
	Content    *string         `json:"content,omitempty"`
	Sequence   int             `json:"sequence"`
	DurationMs *int32          `json:"duration_ms,omitempty"`
	ActionID   *string         `json:"action_id,omitempty"`
	Metadata   json.RawMessage `json:"metadata,omitempty"`
	CreatedAt  string          `json:"created_at"`
	ActorID    string          `json:"actor_id,omitempty"`
	ActorType  string          `json:"actor_type,omitempty"`
	ActorName  string          `json:"actor_name,omitempty"`
	// Terminal marks this step as the run's final event (e.g. the "Run failed" error step). The WS gateway, on seeing it, also emits a terminal run_complete frame on the run topic so the frontend leaves its loading state. Successful/awaiting runs already get that frame from the run-completed event; a failed run only emits this step, so without this flag the live run view stays stuck loading until a hard refresh re-fetches the persisted "failed" status.
	Terminal bool `json:"terminal,omitempty"`
}

type AlertFanoutData struct {
	AccountID        string           `json:"account_id"`
	Category         string           `json:"category"`
	ConversationRef  *ConversationRef `json:"conversation_ref,omitempty"`
	Kind             string           `json:"kind"` // system_event | alert | chat | agent
	Title            string           `json:"title"`
	Body             string           `json:"body,omitempty"`
	Preview          string           `json:"preview,omitempty"`
	TemplateKey      string           `json:"template_key,omitempty"`
	TemplateParams   json.RawMessage  `json:"template_params,omitempty"`
	LinkResourceType string           `json:"link_resource_type,omitempty"`
	LinkResourceID   string           `json:"link_resource_id,omitempty"`
	Priority         string           `json:"priority,omitempty"`
	// Polymorphic sender attribution (user | group | system | agent | apikey).
	SenderType string `json:"sender_type,omitempty"`
	SenderID   string `json:"sender_id,omitempty"`
	SenderName string `json:"sender_name,omitempty"`
	// RecipientAccountUserIDs is an explicit recipient list (account_user ids); empty + Broadcast=true means all active users in the account.
	RecipientAccountUserIDs []string `json:"recipient_account_user_ids,omitempty"`
	// RecipientUserIDs are user ids (us_) the fan-out resolves to account_user ids within AccountID — for producers (e.g. agent-service) that hold the user id, not the account_user id.
	RecipientUserIDs []string        `json:"recipient_user_ids,omitempty"`
	Broadcast        bool            `json:"broadcast,omitempty"`
	DedupeKey        string          `json:"dedupe_key,omitempty"`
	Metadata         json.RawMessage `json:"metadata,omitempty"`
}

type BulkOperation string

type ChatHistoryMessage struct {
	// Role is "assistant" for the dispatched agent's own earlier replies, "user" for everyone else.
	Role string `json:"role"`
	// Name is the sender's display name when known (people); empty for agents.
	Name string `json:"name,omitempty"`
	// AgentConfigID is set when a *different* agent authored this turn. Its display name lives in agent-service (not resolvable in notif-service), so it's carried here and resolved into Name when the run is created. Empty for people and the dispatched agent's own turns.
	AgentConfigID string `json:"agent_config_id,omitempty"`
	Body          string `json:"body"`
}

type CleanupConfig struct {
	// Interval (optional; default: 24h) is how often the cleanup loop fires after the first run. Each tick triggers a full run that processes up to MaxBatchesPerRun batches for each table.
	Interval time.Duration

	// BatchSize (optional; default: 1000) is the maximum number of expired rows deleted in a single SQL DELETE statement. Keeping this bounded prevents table-lock escalation on MySQL and limits the replication lag each batch introduces.
	BatchSize int

	// MaxBatchesPerRun (optional; default: 100) caps the total number of sequential DELETE batches executed for each table in a single cleanup run. The effective ceiling per run is BatchSize * MaxBatchesPerRun rows per table.
	MaxBatchesPerRun int

	// LeaseName (optional; default: "idempotency-cleanup") identifies the distributed lease this worker acquires before each run so only one pod does the DELETE work.
	LeaseName string

	// LeaseTTL (optional; default: 5m) is how long the lease is held before expiring. A full cleanup run typically completes within a few seconds; the TTL is only a safety net for a crashed holder.
	LeaseTTL time.Duration

	// ScheduleLocation (optional; default: America/New_York) is the timezone used to determine when "midnight" falls for the first scheduled run. The worker waits until the next midnight in this location before running for the first time, then repeats every Interval thereafter.
	ScheduleLocation *time.Location
}

type CleanupRepo interface {
	// DeleteExpiredIdempotencyKeys deletes up to `limit` rows from the idempotency_key table whose expires_at timestamp has passed. These are the api-gateway–level keys used to deduplicate inbound HTTP requests. Returns the number of rows actually deleted; the caller uses this to decide whether another batch is needed (deleted < limit means the table is caught up).
	DeleteExpiredIdempotencyKeys(ctx context.Context, limit int) (int64, error)

	// DeleteExpiredServiceIdempotencyKeys deletes up to `limit` rows from the service_idempotency_key table whose expires_at timestamp has passed. These are the service-level keys used by individual gRPC handlers to prevent duplicate side effects. Returns the number of rows actually deleted.
	DeleteExpiredServiceIdempotencyKeys(ctx context.Context, limit int) (int64, error)

	// DeleteExpiredDeletedRecords deletes up to `limit` rows from deleted_record older than the retention window. Returns the number of rows actually deleted.
	DeleteExpiredDeletedRecords(ctx context.Context, limit int) (int64, error)

	// DeleteExpiredRequestLogs deletes up to `limit` rows from request_log older than 7 years. Returns the number of rows actually deleted.
	DeleteExpiredRequestLogs(ctx context.Context, limit int) (int64, error)

	// DeleteExpiredAuditEvents deletes up to `limit` rows from audit_event older than 7 years. Returns the number of rows actually deleted.
	DeleteExpiredAuditEvents(ctx context.Context, limit int) (int64, error)
}

type CleanupWorker struct {
	// contains filtered or unexported fields
}

type ConsumeOption func(*ConsumeOptions)

type ConsumeOptions struct {
	// Concurrency is the number of worker goroutines processing deliveries for this queue. The default of 1 preserves strict in-order, one-at-a-time processing. Values above 1 are only safe for queues whose messages are independently processable — no cross-message ordering requirements — such as request-log and audit-event persistence, where each message is an independent row and the inbox pattern deduplicates redeliveries.
	Concurrency int
}

type ConversationRef struct {
	ConversationID    string `json:"conversation_id,omitempty"`
	TopicResourceType string `json:"topic_resource_type,omitempty"`
	TopicResourceID   string `json:"topic_resource_id,omitempty"`
}

type CustomerRegisteredData struct {
	// SellerAccountID is the seller/vendor account whose portal the buyer registered on. The support route is resolved against this account.
	SellerAccountID string `json:"seller_account_id"`
	// CustomerAccountID is the buyer's customer account (the notification links to it).
	CustomerAccountID string `json:"customer_account_id"`
	// CustomerName is the customer's display name (best-effort; may be empty for an existing-customer join, in which case the consumer falls back to the number).
	CustomerName string `json:"customer_name,omitempty"`
	// CustomerNumber is the seller-facing customer number.
	CustomerNumber string `json:"customer_number,omitempty"`
	// RegistrantUserID is the user (us_) who registered.
	RegistrantUserID string `json:"registrant_user_id,omitempty"`
	// IsExistingCustomer is true when the buyer joined an existing customer account rather than creating a new one.
	IsExistingCustomer bool `json:"is_existing_customer,omitempty"`
}

type EmailLogData struct {
	// SesMessageID is the unique message identifier returned by SES, used to correlate delivery status events (bounces, complaints) back to this email.
	SesMessageID string `json:"ses_message_id"`
	// To are the recipient addresses, persisted as email_recipient rows so the log lists and searches by who received it.
	To []string `json:"to,omitempty"`
	// AccountID is the account context for audit logging.
	AccountID *string `json:"account_id,omitempty"`
	// SentByID is the agent who triggered the email for audit logging.
	SentByID *string `json:"sent_by_id,omitempty"`
	// Subject is the email subject line, stored in the audit record for quick reference without needing to look up the original template.
	Subject string `json:"subject"`
	// Filename is the name of any attachment included with the email.
	Filename *string `json:"filename,omitempty"`
}

type EmailSendData struct {
	// To is the list of recipient email addresses.
	To []string `json:"to"`
	// Subject is the email subject line.
	Subject string `json:"subject"`
	// TemplateID identifies which SES email template to render.
	TemplateID constants.EmailTemplate `json:"template_id"`
	// Params are key-value pairs passed to the template engine for variable substitution (e.g. user name, verification link).
	Params map[string]any `json:"params,omitempty"`
	// SendAs overrides the default sender address (e.g. "support@openmrp.ai"). When nil the notification-service uses its configured default sender.
	SendAs *string `json:"send_as,omitempty"`
	// AccountID is the account context for the email, used for audit logging.
	AccountID *string `json:"account_id,omitempty"`
	// SentByID is the agent who triggered the email, used for audit logging.
	SentByID *string `json:"sent_by_id,omitempty"`
	// AttachmentData is the base64-encoded attachment content. When present, the notification-service sends a raw MIME email with the attachment.
	AttachmentData *string `json:"attachment_data,omitempty"`
	// AttachmentFilename is the filename for the attachment.
	AttachmentFilename *string `json:"attachment_filename,omitempty"`
	// AttachmentContentType is the MIME content type for the attachment.
	AttachmentContentType *string `json:"attachment_content_type,omitempty"`
}

type Enqueuer struct {
	// contains filtered or unexported fields
}

type EnqueuerConfig struct {
	// ServiceName (required) identifies which service owns this enqueuer instance. Stamped onto rows this service writes and used in log messages; it does not scope the poll, which claims pending rows from every service sharing the database.
	ServiceName string

	// PlatformMode (optional) is the platform mode. When set to "test", default intervals are minimized so e2e runs observe async side-effects quickly (see WithDefaults).
	PlatformMode constants.PlatformMode

	// LockOwner (optional; default: "{hostname}-{pid}") is a unique identifier for this process instance, used to claim outbox messages via optimistic locking.
	LockOwner string

	// PollInterval (optional; default: 250ms in production, 10ms in test) controls how frequently the enqueuer polls the outbox table for pending messages while there is work to do.
	PollInterval time.Duration

	// MaxPollInterval (optional; default: 30s in production, == PollInterval in test) is the ceiling for idle backoff. When consecutive polls find nothing, the interval doubles from PollInterval up to this value so an empty outbox is not queried at full rate. Any poll that finds work resets the interval to PollInterval, so pickup latency and throughput under load are unchanged; only the steady-state idle poll rate drops. The tradeoff is that the first message after a sustained idle period waits up to MaxPollInterval to be picked up. Must be >= PollInterval (clamped in WithDefaults).
	//
	// The default is deliberately slow because the poll query is not scoped by service_name: every enqueuer on a given database competes for every pending row, so a service that overrides this to a tighter ceiling (notification-service, agent-service) drains the whole table on behalf of the services that do not. Latency-sensitive producers should call Notify() after commit rather than lowering this, and anything that must publish promptly without a kick belongs on a service that overrides the ceiling.
	MaxPollInterval time.Duration

	// BatchSize (optional; default: 100) is the maximum number of outbox messages to lock and publish in a single poll cycle.
	BatchSize int

	// LockDurationSeconds (optional; default: 60) is how long (in seconds) a message remains locked to this enqueuer before the lock expires and the message becomes eligible for another instance to pick up.
	LockDurationSeconds int

	// CleanupInterval (optional; default: 30s) controls how frequently the enqueuer runs its expired-lock cleanup pass, releasing locks held by crashed processes.
	CleanupInterval time.Duration

	// RetryBackoff (optional; default: 1s base, 2x multiplier, 1h max, 25% jitter; in test mode 10ms base, 2x multiplier, 2s max, 10% jitter) configures the exponential backoff with jitter used to compute the delay before retrying a failed outbox message.
	RetryBackoff *retry.Config

	// DBRetryBackoff (optional; default: OutboxDBRetryConfig(PlatformMode) — 3 retries, 25ms initial, 500ms max, 20% jitter in production) configures short retries for transient database lock conflicts while claiming or marking outbox rows.
	DBRetryBackoff *retry.Config

	// RetentionHours (optional; default: 168 i.e. 7 days) is how long published outbox messages are kept before the purge loop deletes them.
	RetentionHours int

	// PurgeInterval (optional; default: 1h) controls how frequently the enqueuer runs its purge loop to delete old published messages.
	PurgeInterval time.Duration

	// PurgeLeaseTTL (optional; default: 5m) bounds how long the purge loop holds its distributed lease. The lease ensures only one pod per service performs the bulk DELETE of published messages each tick.
	PurgeLeaseTTL time.Duration
}

type ExportOperation string

type FailureMonitor struct {
	// contains filtered or unexported fields
}

type FailureMonitorConfig struct {
	// ServiceName (required) identifies which service hosts this monitor. It scopes the distributed lease so the monitor runs on a single pod.
	ServiceName string

	// PlatformMode (optional; default: "") suppresses alert emails in development mode and shortens the default ScanInterval to 1m in test mode.
	PlatformMode constants.PlatformMode

	// Recipient (optional; default: dev@augno.com) is the email address alerts are sent to.
	Recipient string

	// ScanInterval (optional; default: 5m, or 1m in test) controls how frequently the monitor scans for new failures.
	ScanInterval time.Duration

	// CrashStuckMinutes (optional; default: 30) is how long an inbox row may sit unprocessed (no last_error) before the monitor treats it as crash-stuck and alerts on it.
	CrashStuckMinutes int

	// BatchSize (optional; default: 100) caps how many inbox and outbox failures are pulled into a single alert email per scan.
	BatchSize int32

	// LeaseTTL (optional; default: 5m) bounds how long the monitor holds its lease before a crashed holder's claim expires.
	LeaseTTL time.Duration
}

type FailureMonitorRepo interface {
	// ListUnalertedInboxFailures returns inbox rows still in 'received' status with alerted_at IS NULL that either carry a last_error or have sat unprocessed longer than crashStuckMinutes, up to limit rows.
	ListUnalertedInboxFailures(ctx context.Context, crashStuckMinutes int, limit int32) ([]InboxFailure, error)

	// ListUnalertedOutboxFailures returns outbox rows in 'failed' status with alerted_at IS NULL, up to limit rows.
	ListUnalertedOutboxFailures(ctx context.Context, limit int32) ([]OutboxFailure, error)

	// MarkInboxAlerted stamps alerted_at on the given inbox rows so subsequent scans skip them.
	MarkInboxAlerted(ctx context.Context, ids []int64) error

	// MarkOutboxAlerted stamps alerted_at on the given outbox rows so subsequent scans skip them.
	MarkOutboxAlerted(ctx context.Context, ids []int64) error
}

type GenerateProductionScheduleData struct {
	AccountID  string `json:"account_id"`
	ScheduleID string `json:"schedule_id"`
	// PlanningAsOf is stamped by the tick, not read at consume time, so a message that sits in the queue still plans against the moment the cadence fired.
	PlanningAsOf time.Time `json:"planning_as_of"`
	// AutoPublish publishes the version as soon as it solves, for merchants who want the cadence to be the whole workflow.
	AutoPublish bool `json:"auto_publish"`
}

type HubspotSyncCommandData struct {
	// JobID is the type-prefixed HubSpot sync job id (e.g. "igjb_...").
	JobID string `json:"job_id"`
	// AccountID is the account the job belongs to.
	AccountID string `json:"account_id"`
}

type InboxCheckResult struct {
	// IsDuplicate is true when an inbox record already exists for this (message_id, handler) pair.
	IsDuplicate bool
	// AlreadyProcessed is true when the existing record has status "processed", meaning the handler already ran to completion.
	AlreadyProcessed bool
	// HasPreviousError is true when the existing record has a non-nil LastError, indicating the previous attempt failed.
	HasPreviousError bool
	// PreviousError contains the error message from the last failed attempt.
	PreviousError *string
	// ExistingRecord is the full inbox record, available for detailed inspection.
	ExistingRecord *InboxRecord
}

type InboxConsumer struct {
	// contains filtered or unexported fields
}

type InboxFailure struct {
	ID          int64
	MessageID   string
	ServiceName string
	Handler     string
	MessageType string
	Attempts    int
	LastError   *string
	ReceivedAt  time.Time
}

type InboxPurger struct {
	// contains filtered or unexported fields
}

type InboxPurgerConfig struct {
	// ServiceName (required) identifies which service owns this purger. It's included in the lease name so each service scopes its purger independently.
	ServiceName string

	// PlatformMode (optional; default: "") shortens the default PurgeInterval to 1m when test (see WithDefaults); otherwise the production 1h default applies.
	PlatformMode constants.PlatformMode

	// RetentionHours (optional; default: 168 i.e. 7 days) is how long processed inbox records are kept before the purge loop deletes them.
	RetentionHours int

	// PurgeInterval (optional; default: 1h) controls how frequently the purger runs its purge loop to delete old processed records.
	PurgeInterval time.Duration

	// BatchSize (optional; default: 1000) is the maximum number of processed inbox records to delete in a single SQL DELETE statement.
	BatchSize int32

	// LeaseTTL (optional; default: 5m) bounds how long the purger holds its lease before a crashed holder's claim expires.
	LeaseTTL time.Duration
}

type InboxPurgerRepo interface {
	// PurgeProcessed deletes processed inbox records older than retentionHours, up to limit rows per call. Returns the number of rows deleted.
	PurgeProcessed(ctx context.Context, retentionHours int, limit int32) (int64, error)
}

type InboxRecord struct {
	ID              int64
	MessageID       string
	ServiceName     string
	Handler         string
	MessageType     string
	RequestID       *string
	ParentMessageID *string
	Status          InboxStatus
	Attempts        int
	LastError       *string
	ReceivedAt      time.Time
	ProcessedAt     *time.Time
}

type InboxRecordInput struct {
	// MessageID is the globally unique identifier from the AMQP MessageId header.
	MessageID string
	// ServiceName identifies which service is consuming the message.
	ServiceName string
	// Handler is the logical handler name (e.g. "notification.send_email") used to scope deduplication — the same message delivered to different handlers is processed independently.
	Handler string
	// MessageType is the AMQP routing key / message type for observability.
	MessageType string
	// RequestID ties this message back to the originating request for tracing.
	RequestID string
	// ParentMessageID links to the message that caused this one to be emitted.
	ParentMessageID string
}

type InboxRepo interface {
	// TryInsert attempts to insert a new inbox record with status "received". On success it returns the auto-generated record ID. On duplicate (MySQL error 1062 from the unique index on message_id + handler), it returns 0 and the MySQL error so the caller can branch into duplicate-handling logic.
	TryInsert(ctx context.Context, input InboxRecordInput) (int64, error)

	// GetByMessageAndHandler retrieves the existing inbox record for a given message and handler combination. Used by handleDuplicate to inspect the prior record's status and decide whether to skip, retry, or trigger crash recovery.
	GetByMessageAndHandler(ctx context.Context, messageID, handler string) (*InboxRecord, error)

	// MarkProcessed transitions the record to "processed" status and sets processed_at. Called after the handler completes successfully.
	MarkProcessed(ctx context.Context, id int64) error

	// MarkFailed increments the attempt count and stores the error message from the most recent failed attempt. The record stays in "received" status so it can be retried on re-delivery.
	MarkFailed(ctx context.Context, id int64, errMsg string) error
}

type InboxStatus string

type InvoiceCreatedReportData struct {
	// Names the account the invoice was created for.
	AccountID string `json:"account_id"`
	// Identifies the invoice that triggered the report.
	InvoiceID string `json:"invoice_id"`
}

type MessageBroker interface {
	// PublishMessage publishes the message to the given exchange with the specified routing key.
	PublishMessage(ctx context.Context, exchange, routingKey string, message contracts.AmqpMessage) error
	// ConsumeMessages consumes messages from the given queue and invokes the handler for each delivery.
	ConsumeMessages(ctx context.Context, queueName string, handler MessageHandler, opts ...ConsumeOption) error
	// ConsumeFanout declares a per-instance ephemeral (non-durable, exclusive, auto-delete) queue named "<baseName>.<instance-suffix>", binds it to the given routing keys on the application exchange, and consumes from it. Because every process that calls this gets its OWN queue, each receives a copy of every matching message — true fan-out. This is the correct primitive for realtime WebSocket delivery, where every api-gateway replica holds a distinct set of client sockets and must therefore see every event. Contrast with ConsumeMessages, whose callers share one durable queue and thus compete for deliveries (work-queue semantics). The per-instance queue dies with the process, so undelivered realtime events are simply dropped — acceptable because the persisted rows remain the source of truth.
	ConsumeFanout(ctx context.Context, baseName string, routingKeys []string, handler MessageHandler, opts ...ConsumeOption) error
	// IsReady reports whether the broker connection and channel are ready for use.
	IsReady() bool
	// Close shuts down the AMQP channel and connection. Safe to call multiple times.
	Close()
}

type MessageHandler func(context.Context, amqp.Delivery) error

type OutboxEnqueuerRepo interface {
	// AcquireAndLock atomically selects up to `limit` pending messages whose next_run_at has passed and locks them to the given lockOwner for lockDurationSeconds. Returns the locked messages for publishing.
	AcquireAndLock(ctx context.Context, lockOwner string, limit int, lockDurationSeconds int) ([]*OutboxMessage, error)

	// MarkPublished updates the given messages' status to 'published' with a timestamp, preserving the records for audit and debugging purposes. The enqueuer calls this once per batch with every id it published, so the implementation should issue a single set-based UPDATE.
	MarkPublished(ctx context.Context, ids []int64) error

	// MarkFailed increments the message's attempt count, records the error message, and schedules the next retry after retryDelaySecs seconds. If MaxAttempts is exceeded the message remains in "failed" status for manual investigation.
	MarkFailed(ctx context.Context, id int64, errorMsg string, retryDelaySecs int) error

	// CleanupExpiredLocks releases locks held by enqueuer instances that have crashed or stalled (lock_expires_at < now), making those messages eligible for re-acquisition by any healthy enqueuer.
	CleanupExpiredLocks(ctx context.Context, limit int32) (int64, error)

	// PurgePublished deletes published outbox messages older than retentionHours, up to limit rows per call. Returns the number of rows deleted.
	PurgePublished(ctx context.Context, retentionHours int, limit int32) (int64, error)
}

type OutboxFailure struct {
	ID          int64
	MessageID   string
	ServiceName string
	MessageType string
	Destination string
	RoutingKey  string
	Attempts    int
	MaxAttempts int
	LastError   *string
	CreatedAt   time.Time
}

type OutboxMessage struct {
	ID              int64
	MessageID       string
	ServiceName     string
	MessageType     string
	Destination     string
	RoutingKey      string
	Headers         map[string]any
	Payload         contracts.AmqpMessage
	Status          OutboxStatus
	Attempts        int
	MaxAttempts     int
	NextRunAt       time.Time
	LockedAt        *time.Time
	LockOwner       *string
	LockExpiresAt   *time.Time
	LastError       *string
	PublishedAt     *time.Time
	RequestID       *string
	ParentMessageID *string
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type OutboxMessageInput struct {
	// MessageID is the globally unique identifier for this message (e.g. mg_abc123).
	MessageID string
	// ServiceName identifies the service that created the message (e.g. "auth-service").
	ServiceName string
	// MessageType categorizes the message for routing and consumer dispatch (e.g. "notification.cmd.send_email").
	MessageType string
	// Destination is the AMQP exchange the message should be published to.
	Destination string
	// RoutingKey is the AMQP routing key used for topic-based queue binding.
	RoutingKey string
	// Payload is the structured message body that will be JSON-serialized and published.
	Payload contracts.AmqpMessage
	// MaxAttempts caps how many times the enqueuer will retry publishing before giving up.
	MaxAttempts int
	// DelaySeconds (optional; default 0 = available immediately) defers first delivery by scheduling next_run_at that many seconds into the future. Used for backoff on re-enqueue (e.g. bounded auto-retry of a transient failure) so the message is not republished into a still-failing dependency. Not every service's outbox Create honors this; today only agent-service does.
	DelaySeconds int
}

type OutboxNotifier interface {
	Notify()
}

type OutboxRepo interface {
	// Create inserts a new outbox message within the current transaction. The message starts in "pending" status and will be picked up by the Enqueuer's poll loop.
	Create(ctx context.Context, input OutboxMessageInput) (int64, error)
}

type OutboxStatus string

type RabbitMQConfig struct {
	// URI (required) is the rabbitMQ connection URI.
	URI string

	// ConnectionTimeout (optional; default: 2m) is the overall timeout for the initial connection attempt.
	ConnectionTimeout time.Duration

	// MaxRetries (optional; default: 10) is the maximum number of connection dial retries.
	MaxRetries int

	// InitialRetryWait (optional; default: 1s) is the starting backoff interval between connection retries.
	InitialRetryWait time.Duration

	// MaxRetryWait (optional; default: 10s) is the maximum backoff interval between connection retries.
	MaxRetryWait time.Duration

	// PrefetchCount (optional; default: 1) is the QoS prefetch limit per consumer.
	PrefetchCount int

	// ReconnectDelay (optional; default: 5s) is how long to wait before retrying after a consumer failure.
	ReconnectDelay time.Duration
}

type RealtimeDeliveryData struct {
	AccountID string `json:"account_id"`
	// RecipientUserID is the user id (us_) used as the WS user-topic key (the gateway subscribes user:<user_id> from the validated identity's actor id).
	RecipientUserID string `json:"recipient_user_id,omitempty"`
	// RecipientAccountUserID is the per-account recipient (acus_) the notification belongs to.
	RecipientAccountUserID string `json:"recipient_account_user_id,omitempty"`
	// ConversationID targets the per-conversation topic (live chat).
	ConversationID string `json:"conversation_id,omitempty"`
	// AnnouncementID targets the per-account broadcast topic (account:<account_id>).
	AnnouncementID string `json:"announcement_id,omitempty"`
	// Event is the client-facing event name: notification.created | announcement.created | message.created | conversation.updated | unread.changed | account.unread_hint.
	Event string `json:"event"`
	// Visibility is the audience of a message-bearing frame (internal | external | system); empty for non-message events. SAFETY: a customer-subscribed conversation socket must drop frames whose Visibility is "internal" so an internal note is never delivered to the customer. The authoritative guarantee is the visibility-filtered read path; this lets the realtime layer enforce the same.
	Visibility     string          `json:"visibility,omitempty"`
	NotificationID string          `json:"notification_id,omitempty"`
	MessageID      string          `json:"message_id,omitempty"`
	Sequence       int64           `json:"sequence,omitempty"`
	UnreadCount    *int64          `json:"unread_count,omitempty"`
	Payload        json.RawMessage `json:"payload,omitempty"`
}

type SalesOrderCreatedData struct {
	// SalesOrderID is the type-prefixed ID of the created order (e.g. "so_...").
	SalesOrderID string `json:"sales_order_id"`
	// AccountID is the owner/seller account the order belongs to.
	AccountID string `json:"account_id"`
	// BuyerAccountID is the customer account the order was created for.
	BuyerAccountID string `json:"buyer_account_id"`
	// Number is the human-facing order number.
	Number string `json:"number"`
	// StatusCode is the order's status at creation (e.g. "estimate").
	StatusCode string `json:"status_code"`
}

type SalesOrderShippingUpdatedData struct {
	// SalesOrderID is the type-prefixed ID of the updated order.
	SalesOrderID string `json:"sales_order_id"`
	// AccountID is the owner/seller account the order belongs to.
	AccountID string `json:"account_id"`
}

type SeatChangeReportData struct {
	// AccountID is the account whose seat count changed.
	AccountID string `json:"account_id"`
}

type SeatSyncData struct {
	// AccountID is the account whose seat count changed.
	AccountID string `json:"account_id"`
}