events

type Actor = ent.Actor

type AuditEntry struct {
	WorkspaceID int64          `json:"workspaceId"`
	Actor       Actor          `json:"actor"`
	Action      string         `json:"action"` // <entity>.<verb>
	TargetType  string         `json:"targetType"`
	TargetID    string         `json:"targetId,omitempty"`
	TargetName  string         `json:"targetName,omitempty"`
	Diff        map[string]any `json:"diff,omitempty"`
	RequestID   string         `json:"requestId,omitempty"`
	IP          string         `json:"ip,omitempty"`
	UserAgent   string         `json:"userAgent,omitempty"`
}

type AuditFilter struct {
	// From is inclusive and To exclusive; a zero time is unbounded.
	From, To   time.Time
	ActorKind  string
	ActorID    string
	Action     string
	TargetType string
	TargetID   string
	IP         string
	RequestID  string
}

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

type CollectedEvent struct {
	WorkspaceID int64          `json:"workspaceId"`
	ContactID   int64          `json:"contactId,omitempty"` // 0 ⇒ anonymous
	VisitorID   string         `json:"visitorId,omitempty"`
	SubjectID   string         `json:"subjectId,omitempty"`
	Action      string         `json:"action"`
	Email       string         `json:"email,omitempty"`
	Phone       string         `json:"phone,omitempty"`
	Properties  map[string]any `json:"properties,omitempty"`
	OccurredAt  time.Time      `json:"occurredAt,omitzero"`
	// DedupID is the persist idempotency key of an event the client gave a clientEventId
	// (DedupKey: the source, the Workspace and that id). Empty for an event without one.
	DedupID string `json:"dedupId,omitempty"`
	// Backfill marks an event loaded from history: it is recorded, but no Automation enrolls
	// on it and no webhook endpoint receives it.
	Backfill bool `json:"backfill,omitempty"`
}

type Consumer struct {
	Name   string
	Handle func(ctx context.Context, env Envelope) error
}

type ContactCreated struct {
	WorkspaceID int64  `json:"workspaceId"`
	ContactID   int64  `json:"contactId"`
	Email       string `json:"email"`
}

type ContactErased struct {
	WorkspaceID    int64  `json:"workspaceId"`
	SubjectID      string `json:"subjectId"`
	IdentifierKind string `json:"identifierKind"` // what the requester identified the person by
	RequesterKind  string `json:"requesterKind"`  // user|api_token
	RequesterID    int64  `json:"requesterId"`

	// The keys Erasure matched on (ADR 0045), for the Erasures Export stream: the erased
	// Contact's id (the row is gone, so the id points at nothing), the anonymous devices
	// erased with it, and SHA-256 (hex) of the lowercased address and of the phone, computed
	// before publishing so no address or phone reaches the outbox. Empty when there was none.
	ContactID  int64    `json:"contactId,omitempty"`
	VisitorIDs []string `json:"visitorIds,omitempty"`
	EmailHash  string   `json:"emailHash,omitempty"`
	PhoneHash  string   `json:"phoneHash,omitempty"`
}

type DomainEvent interface {
	EventName() string   // bus type / registry key
	EventVersion() int   // schema version
	Workspace() int64    // owning workspace
	Project() Projection // how this event maps to the Event row + trigger
}

type EmailDelivery struct {
	Action      string `json:"action"` // email.delivered|email.delayed|email.dropped|email.bounced|email.complained
	WorkspaceID int64  `json:"workspaceId"`
	ContactID   int64  `json:"contactId,omitempty"`
	Email       string `json:"email"`
	BounceKind  string `json:"bounceKind,omitempty"` // permanent|transient (bounces only)
	Provider    string `json:"provider,omitempty"`   // ses, ...
	// SendingDomain is the domain the failed message was sent from (ADR 0011), so the
	// complaint/bounce rate can be grained per Sending domain.
	SendingDomain string `json:"sendingDomain,omitempty"`
	// Reason is the provider's short explanation of a bounce, delay or drop, at most
	// 500 characters.
	Reason string `json:"reason,omitempty"`
	// ProviderMessageID is the id the notice named, kept even when no Outbound message
	// matched it.
	ProviderMessageID string `json:"providerMessageId,omitempty"`
	// The Outbound message the notice was linked to, and where that message came from.
	OutboundMessageID int64  `json:"outboundMessageId,omitempty"`
	Surface           string `json:"surface,omitempty"`
	SendingSource     string `json:"sendingSource,omitempty"`
	BroadcastID       int64  `json:"broadcastId,omitempty"`
	AutomationID      int64  `json:"automationId,omitempty"`
	// DedupID is the stable upstream id (e.g. SNS messageId + recipient) used as
	// the envelope id so a redelivered provider notification dedupes at persist.
	DedupID string `json:"dedupId,omitempty"`
	// Captured is set when the message went through a sender that delivers nowhere outside.
	Captured bool `json:"captured,omitempty"`
}

type EmailEngagement struct {
	Action      string `json:"action"` // email.sent|email.opened|email.clicked|email.unsubscribed
	WorkspaceID int64  `json:"workspaceId"`
	ContactID   int64  `json:"contactId"`
	Email       string `json:"email"`
	BroadcastID int64  `json:"broadcastId"`
	URL         string `json:"url,omitempty"`
	DedupID     string `json:"dedupId,omitempty"`
	// Machine is set on an open or click made by software (ADR 0053): it stays in the Event log
	// but counts toward no figure, sets no rollup and starts no Automation.
	Machine bool `json:"machine,omitempty"`

	// The envelope an Outbound send stamps on email.sent (ADR 0015, ADR 0011):
	// which surface sent it, under which Sending source and Sending domain, and the
	// ids that tie the Event back to the Outbound message and the provider's copy.
	Surface           string `json:"surface,omitempty"`
	SendingSource     string `json:"sendingSource,omitempty"`
	SendingDomain     string `json:"sendingDomain,omitempty"`
	AutomationID      int64  `json:"automationId,omitempty"`
	OutboundMessageID int64  `json:"outboundMessageId,omitempty"`
	ProviderMessageID string `json:"providerMessageId,omitempty"`
	// Captured is set when the send went through a sender that delivers nowhere outside (a
	// Test inbox): Activity says "captured, not delivered".
	Captured bool `json:"captured,omitempty"`
}

type Enqueuer interface {
	Enqueue(ctx context.Context, args river.JobArgs, opts *river.InsertOpts) error
}

type Enroller interface {
	OnEvent(ctx context.Context, workspaceID, contactID int64, action string, sourceAutomationID int64) error
}

type Envelope struct {
	ID          string          `json:"id"`          // ULID; the watermill message id
	Name        string          `json:"name"`        // bus event type (registry key)
	Version     int             `json:"version"`     // schema version of Data
	WorkspaceID int64           `json:"workspaceId"` // every event is workspace-scoped
	OccurredAt  time.Time       `json:"occurredAt"`
	Data        json.RawMessage `json:"data"` // the typed event, marshaled
	// DedupKey is the persist idempotency key. Empty ⇒ use ID. An event with a
	// natural upstream id (a provider notification) sets it so at-least-once
	// redelivery dedupes, while ID stays a short ULID for the message-id column.
	DedupKey string `json:"dedupKey,omitempty"`
	// RecordedAt is when the event was published, as opposed to OccurredAt, which a client may
	// backdate. Rules act only on events recorded after they were activated (ADR 0054).
	RecordedAt time.Time `json:"recordedAt"`
	// CausedBy names what published the event when it was not a customer or a provider: an
	// Action of a Rule stamps it on any event it publishes, and the Rule consumer skips an event
	// that carries it, so Rules never chain (ADR 0054). No Action publishes an event today, so
	// nothing stamps it yet; the consumer honours it already.
	CausedBy string `json:"causedBy,omitempty"`
}

type JobInserter interface {
	InsertTx(ctx context.Context, tx *sql.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}

type MarketingConfirmed struct {
	WorkspaceID int64  `json:"workspaceId"`
	ContactID   int64  `json:"contactId,omitempty"`
	Email       string `json:"email"`
	Provenance  string `json:"provenance"`   // double_opt_in|grandfathered|imported
	IP          string `json:"ip,omitempty"` // confirming client IP (double_opt_in only)
}

type Projection struct {
	Subject    string         // → events.subject_id snapshot; "" ⇒ anonymous
	Action     string         // → events.action; also the automation trigger key
	Email      string         // "" ⇒ unset
	Phone      string         // "" ⇒ unset
	Properties map[string]any // → events.properties (opaque for customer events)
	OccurredAt time.Time      // zero ⇒ publish time
	// ContactID is the authoritative Contact link (→ events.contact_id) AND the
	// automations enroll target; 0 ⇒ none (anonymous, pre-Identify).
	ContactID int64
	// VisitorID is the anonymous device (→ events.visitor_id), kept so an anonymous
	// event can be stitched onto a Contact at Identify. "" ⇒ unset.
	VisitorID string
	// AutomationID is the Automation whose email the Event came from, 0 for any other Event. An
	// Automation never starts from an Event of its own email (ADR 0053).
	AutomationID int64
	// Machine marks an open or click made by software (ADR 0053). It is recorded, but starts no
	// Automation.
	Machine bool
}

type PruneResult struct {
	// Deleted is the number of outbox rows removed.
	Deleted int64
	// RetiredGroups is the number of offsets rows removed for consumer groups no
	// longer registered in code.
	RetiredGroups int64
	// Skipped is true when the run deleted no outbox rows because a registered
	// consumer group has no usable cursor yet (no offsets row, or a NULL ack).
	Skipped bool
}

type Publisher interface {
	Publish(_ context.Context, ev DomainEvent) error
}

type PurgingPublisher interface {
	Publisher
	QueuePurger
}

type QueuePurger interface {
	// PurgeOutbox deletes the Workspace's outbox envelopes that name the Contact,
	// by id or by one of its destinations (matched case-insensitively).
	PurgeOutbox(ctx context.Context, workspaceID, contactID int64, destinations []string) error
	// PurgeJobs deletes the river jobs of kind that are not running and whose
	// args integer field key is one of ids. A running job is left to finish: its
	// worker re-checks that what it refers to still exists.
	PurgeJobs(ctx context.Context, key jobkind.Key, ids []int64) error
	// PurgeWebhookJobs deletes the queued deliveries to the Workspace's own webhook
	// endpoints whose body names the Contact (contactId) or one of its
	// destinations (data.email, case-insensitively). The body is the event payload
	// the endpoint would receive. A running delivery is left to finish.
	PurgeWebhookJobs(ctx context.Context, workspaceID, contactID int64, destinations []string) error
}

type RejectionError struct{ Reason string }

type RuleEvaluator interface {
	OnRuleEvent(ctx context.Context, ev RuleEvent) error
}

type RuleEvent struct {
	WorkspaceID int64
	ContactID   int64
	Action      string
	SourceID    string
	RecordedAt  time.Time
	Properties  map[string]any
}

type SubscribeOption func(*watermillsql.SubscriberConfig)

type TrackingDomainChanged struct {
	WorkspaceID     int64  `json:"workspaceId"`
	SendingDomainID int64  `json:"sendingDomainId"`
	Host            string `json:"host"`
	From            string `json:"from"`
	To              string `json:"to"`
}

type Unprojected interface {
	Unprojected()
}

type WebhookDispatcher interface {
	Dispatch(ctx context.Context, s *ent.Scoped, eventName, deliveryID string, body []byte) error
}