Class: Moderate::Event

Inherits:
Data
  • Object
show all
Defined in:
lib/moderate/event.rb

Overview

The stable envelope every notifiable/auditable moment travels in.

‘Moderate.notify` and `Moderate.audit` both hand the host’s hook ONE of these, so a single ‘config.notify` lambda can `case event.name` and fan out to email (goodmail), admin alerts (telegrama), and in-app + push (noticed) without any of those channels knowing about each other. See docs/notifications.md.

The fields are the contract the docs promise the host can rely on:

event.name        # Symbol — which moment, e.g. :report_decision
event.subject     # the record this is about (a Report / Flag / Block / Appeal / Notice)
event.actor       # who triggered it (a moderator, a user, or nil for system events)
event.recipients  # Array — already resolved to the right people to notify
event.payload     # Hash of event-specific context, ALWAYS including :summary
event.occurred_at # when it happened
event.to_h        # the whole envelope as a Hash (for logging, tests, noticed params)

Immutable value object (‘Data.define`, Ruby 3.2+). The host never constructs one — the gem’s services do — the host only reads it.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, subject: nil, actor: nil, recipients: nil, payload: nil, occurred_at: Time.now, id: SecureRandom.uuid) ⇒ Event

Keyword constructor with forgiving defaults so internal call sites stay terse. ‘recipients` is coerced to a compacted Array (an event may target one user, several, or none — `content_flagged` has no user recipient by design, so an empty array is normal and correct). `payload` is symbolized for stable access (hooks read `event.payload`).



30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/moderate/event.rb', line 30

def initialize(name:, subject: nil, actor: nil, recipients: nil, payload: nil,
               occurred_at: Time.now, id: SecureRandom.uuid)
  super(
    name: name.to_sym,
    subject: subject,
    actor: actor,
    recipients: Array(recipients).compact,
    payload: symbolize(payload),
    occurred_at: occurred_at,
    id: id
  )
end

Instance Attribute Details

#actor ⇒ Object (readonly)

Returns the value of attribute actor

Returns:

  • (Object) —

    the current value of actor



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def actor
  @actor
end

#id ⇒ Object (readonly)

Returns the value of attribute id

Returns:

  • (Object) —

    the current value of id



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def id
  @id
end

#name ⇒ Object (readonly)

Returns the value of attribute name

Returns:

  • (Object) —

    the current value of name



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def name
  @name
end

#occurred_at ⇒ Object (readonly)

Returns the value of attribute occurred_at

Returns:

  • (Object) —

    the current value of occurred_at



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def occurred_at
  @occurred_at
end

#payload ⇒ Object (readonly)

Returns the value of attribute payload

Returns:

  • (Object) —

    the current value of payload



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def payload
  @payload
end

#recipients ⇒ Object (readonly)

Returns the value of attribute recipients

Returns:

  • (Object) —

    the current value of recipients



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def recipients
  @recipients
end

#subject ⇒ Object (readonly)

Returns the value of attribute subject

Returns:

  • (Object) —

    the current value of subject



24
25
26
 
# File 'lib/moderate/event.rb', line 24

def subject
  @subject
end

Instance Method Details

#summary ⇒ Object

The one-line, redaction-safe description of what happened. Built for the admin Telegram ping (“Telegrama.send_message(event.payload)”), so we surface it as a first-class reader rather than making every hook reach into the payload Hash. Falls back to the event name if a producer forgot it.



63
64
65
 
# File 'lib/moderate/event.rb', line 63

def summary
  payload[:summary] || name.to_s
end

#to_h ⇒ Object

The whole envelope as a plain Hash. docs/notifications.md tells hosts to pass ‘event.to_h` (not the raw object) into `noticed`, because noticed serializes params to the database and a Hash of GlobalID-able records + scalars stores cleanly. Keep this a flat, predictable shape.



47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/moderate/event.rb', line 47

def to_h
  {
    name: name,
    subject: subject,
    actor: actor,
    recipients: recipients,
    payload: payload,
    occurred_at: occurred_at,
    id: id
  }
end