Class: SimpleConnect::Api::Events

Inherits:
Object
  • Object
show all
Includes:
ResponseAttachment
Defined in:
lib/simple_connect/api/events.rb

Overview

Events resource. Holds the shared Request and the endpoint URI; exposes #deliver (POST a domain event) and #detail (GET a previously-ingested event by its event_id).

Event-key validation is opt-in. Pass ‘event_keys:` to Client.new to enforce a whitelist client-side; omit it and the server becomes the source of truth (unknown keys return 422 from the server). The gem ships no hardcoded event list — each provider owns its own taxonomy.

Constant Summary collapse

DEFAULT_LANGUAGE = 
"en"

Instance Method Summary collapse

Constructor Details

#initialize(request:, endpoint_uri:, event_keys: nil) ⇒ Events

Returns a new instance of Events.



18
19
20
21
22
 
# File 'lib/simple_connect/api/events.rb', line 18

def initialize(request:, endpoint_uri:, event_keys: nil)
  @request      = request
  @endpoint_uri = endpoint_uri
  @event_keys   = event_keys&.map(&:to_s)&.freeze
end

Instance Method Details

#deliver(event_key, recipient:, event: {}) ⇒ Object

Deliver a domain event.

events.deliver(
  "customer_payment_received",
  recipient: { mobile_no: "+919812345678", name: "Ramesh Kumar" },
  event: {
    event_id:       "pp_payment_42",
    customer_name:  "Ramesh Kumar",
    payment_amount: "450.00"
  }
)

The two hashes mirror the wire body 1:1 — ‘recipient` is used for routing, `event` carries template-variable fields. The envelope (`event_id`, `occurred_at`, `language`) is auto-filled into `event` when omitted: `event_id` defaults to a random `evt_<hex>`, `occurred_at` to now, `language` to “en”. `event` is always set to `event_key` — passing one is ignored.

Raises:

  • (ArgumentError) 


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/simple_connect/api/events.rb', line 42

def deliver(event_key, recipient:, event: {})
  event_key = event_key.to_s
  raise ArgumentError, "event_key is required" if event_key.empty?

  recipient = stringify_keys(recipient)
  raise ArgumentError, "recipient[:mobile_no] is required" if recipient["mobile_no"].to_s.strip.empty?

  if @event_keys && !@event_keys.include?(event_key)
    raise SimpleConnect::UnknownEventError,
          "Unknown event_key '#{event_key}'. Must be one of: #{@event_keys.join(", ")}"
  end

  body = build_body(event_key, recipient: recipient, event: stringify_keys(event))
  attach_response(@request.post(@endpoint_uri, body: body), Responses::DeliverResponse)
end

#detail(event_id) ⇒ Object

Raises:

  • (ArgumentError) 


58
59
60
61
62
 
# File 'lib/simple_connect/api/events.rb', line 58

def detail(event_id)
  raise ArgumentError, "event_id is required" if event_id.to_s.strip.empty?

  attach_response(@request.get(detail_uri(event_id)), Responses::EventResponse)
end