simple_connect-client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1ab061c2118ee363fa9fdc9c1f69518a247cf55297d5b8dbf0de893c3507823
-  data.tar.gz: ce307f5e3403aead072705a621115308a573da3839bf5121b2e80b14a40503bc
+  metadata.gz: 80608e802aa6273143cb24d056f08abc1541dac6223371eae39c2611ed2ab99e
+  data.tar.gz: 9c8e9130fd84bda6b19eaccf5f57a68ff81dc186070f19ef1834114981dbb8bb
 SHA512:
-  metadata.gz: cdc8f0ea63a0d3a133a871e0a0cd9ab21649d70ece906e1b54a14f7f36254186e80a5015e4890e12d9b4fdb673e89cb6a29aa941708e2c73bdef60761a7ed996
-  data.tar.gz: f800d93c034416cd8b143283f8fe9a354bc768e932f7ad399476e0ee134599adedaf59c7cec3ccd04ff330253bab4efae2ade766a0d879f6bb45cd301dddf35d
+  metadata.gz: ad8d5b28164c2598aeb32ee7bf0db42eec12ab15a0fed501d12b4cd9e33dfda11ac69ae24e21be0def68773c1119c40d020d31c0e77aae5b993458a1cc02e7b9
+  data.tar.gz: 2d578d852fa29a83400e6fecd49918cbddc118ebe7e846f64496e04d79b88ea7c3d3844c4f6f2c22c55900085e3b6872c2b8cc1a0a04810cc9c5b1cc63abfd29

data/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-30
+
+### Added
+
+- `events.deliver` response now embeds the persisted event-log row plus
+  the (optional) linked WhatsApp message under the same
+  `event_log` / `message` keys that `events.detail` already uses. The
+  new `DeliverResponse#event` returns this as an `EventResponse` —
+  callers can read `result.data.event.status`, `.error_text`,
+  `.skipped?`, `.dispatched?`, `.message`, etc., to see at a glance
+  whether the event was actually queued for dispatch (`"received"`) or
+  skipped because the integration is paused / the per-event flow is
+  disabled (both still return 202 server-side, because the event was
+  logged for audit). Previously the only deliver-time signal was
+  `#log_id` / `#event_id`, so a paused integration looked identical to
+  a healthy one from the sender's perspective.
+- `EventResponse` is now reused for both endpoints — no new response
+  class. Its existing public surface is unchanged.
+
+### Compatibility
+
+- **Server requirement**: the new `event_log` / `message` fields are
+  populated by SimpleWaConnect server ≥ v0.3.0. Older servers return
+  the v0.2.0 shape (`status`, `log_id`, `event_id`, `duplicate`,
+  `used_previous_secret`); `DeliverResponse#event` returns `nil` in
+  that case so existing code continues to work unmodified.
+- The flat `#log_id` / `#event_id` accessors on `DeliverResponse` are
+  preserved — existing callers do not need to change anything.
+
+## [0.2.0] - 2026-04-21
+
+### Changed
+
+- **BREAKING** — outgoing event body reshaped to match the new server
+  contract. The flat envelope (`{ event, event_id, occurred_at, language,
+  customer_name, customer_mobile_no, ... }`) is now nested as
+  `{ "recipient": { name, mobile_no }, "event": { event_id, name,
+  occurred_at, language, ...fields } }`. The server (SimpleWaConnect ≥ this
+  release) rejects the old flat shape with 422.
+- **BREAKING** — `events.deliver` signature simplified to mirror the wire
+  body: `deliver(event_key, recipient:, event: {})`. `recipient` is a hash
+  (`mobile_no:` required, `name:` optional); `event` is a hash of
+  event-specific fields plus optional envelope overrides (`event_id`,
+  `occurred_at`, `language`). Old callers that passed `customer_mobile_no:`
+  as routing info, a positional `fields` hash, or envelope kwargs directly
+  (`event_id:`, `language:`, `occurred_at:`) must move all of those into
+  the two hashes.
+
 ## [0.1.0] - 2026-04-20
 
 ### Added
@@ -32,5 +80,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ruby 3.2+.
 - No runtime gem dependencies (stdlib only).
 
-[unreleased]: https://github.com/GemsEssence/SimpleWaConnect/compare/simple_connect-client-v0.1.0...HEAD
+[unreleased]: https://github.com/GemsEssence/SimpleWaConnect/compare/simple_connect-client-v0.3.0...HEAD
+[0.3.0]: https://github.com/GemsEssence/SimpleWaConnect/compare/simple_connect-client-v0.2.0...simple_connect-client-v0.3.0
+[0.2.0]: https://github.com/GemsEssence/SimpleWaConnect/compare/simple_connect-client-v0.1.0...simple_connect-client-v0.2.0
 [0.1.0]: https://github.com/GemsEssence/SimpleWaConnect/releases/tag/simple_connect-client-v0.1.0

data/README.md

@@ -71,19 +71,34 @@ The client groups calls into two resource objects — `events` and `integrations
 ```ruby
 SIMPLECONNECT.events.deliver(
   "customer_payment_received",
-  customer_name:             "Ramesh Kumar",
-  customer_mobile_no:        "+919812345678",
-  agency_name:               "Acme Dairy",
-  payment_date:              "2026-04-16",
-  payment_mode:              "UPI",
-  payment_amount:            "450.00",
-  customer_total_due_amount: "0.00",
-  event_id:                  "pp_payment_#{payment.id}" # idempotency key
+  recipient: {
+    mobile_no: "+919812345678",   # required — routing target
+    name:      "Ramesh Kumar"     # optional
+  },
+  event: {
+    event_id:                  "pp_payment_#{payment.id}", # idempotency key
+    customer_name:             "Ramesh Kumar",
+    agency_name:               "Acme Dairy",
+    payment_date:              "2026-04-16",
+    payment_mode:              "UPI",
+    payment_amount:            "450.00",
+    customer_total_due_amount: "0.00"
+  }
 )
 ```
 
-Pass an explicit `event_id:` (unique per domain event) for safe retries —
-duplicate event_ids are treated as no-ops by the server.
+The two hashes mirror the wire body 1:1:
+
+- `recipient` is used by SimpleConnect to route the outbound WhatsApp message.
+  `mobile_no` is required, `name` is optional. Fields here are **not** accessible
+  to template variable mappings — to show the customer's name in a message body,
+  duplicate it under `event:` (e.g. `customer_name:`).
+- `event` carries the envelope plus all template-variable fields. Pass an explicit
+  `event_id` (unique per domain event) for safe retries — duplicate `event_id`s
+  are treated as no-ops by the server. If omitted, the client generates
+  `evt_<hex>`. `occurred_at` defaults to now, `language` to `"en"`. Any `name:`
+  you pass inside `event` is ignored — it's always set to the positional
+  `event_key`.
 
 ### Fetch a previously-ingested event
 
@@ -113,7 +128,11 @@ Every resource call returns a `Result` struct with:
 | `data`         | Response?| Typed response object (see below) when the body was parseable; `nil` otherwise          |
 
 ```ruby
-result = SIMPLECONNECT.events.deliver("customer_payment_received", fields)
+result = SIMPLECONNECT.events.deliver(
+  "customer_payment_received",
+  recipient: { mobile_no: "+919812345678", name: "Ramesh" },
+  event:     fields
+)
 if result.success?
   Rails.logger.info("delivered in #{result.attempts} attempt(s); id=#{result.data.event_id}")
 else
@@ -139,7 +158,9 @@ Always check `result.success?` first, then read `result.data`.
 
 ```ruby
 result = SIMPLECONNECT.events.deliver(
-  "customer_payment_received", fields, event_id: "pp_pay_42"
+  "customer_payment_received",
+  recipient: { mobile_no: "+919812345678", name: "Ramesh" },
+  event:     fields.merge(event_id: "pp_pay_42")
 )
 
 if result.success?
@@ -209,7 +230,11 @@ end
 ### Error path → `ErrorResponse`
 
 ```ruby
-result = SIMPLECONNECT.events.deliver("some_event", fields)
+result = SIMPLECONNECT.events.deliver(
+  "some_event",
+  recipient: { mobile_no: "+919812345678" },
+  event:     fields
+)
 
 unless result.success?
   if result.data                 # ErrorResponse (or nil for non-JSON / network errors)
@@ -251,15 +276,15 @@ SIMPLECONNECT = SimpleConnect::Client.new(
 )
 
 class DeliverSimpleConnectEventJob < ApplicationJob
-  def perform(event_key, fields, event_id:)
-    SIMPLECONNECT.events.deliver(event_key, fields, event_id: event_id)
+  def perform(event_key, recipient, event)
+    SIMPLECONNECT.events.deliver(event_key, recipient: recipient, event: event)
   end
 end
 
 DeliverSimpleConnectEventJob.perform_later(
   "customer_payment_received",
-  { customer_name: "...", ... },
-  event_id: "pp_payment_#{payment.id}"
+  { mobile_no: "+919812345678", name: "Ramesh" },
+  { customer_name: "Ramesh", agency_name: "Acme", event_id: "pp_payment_#{payment.id}" }
 )
 ```
 

data/lib/simple_connect/api/events.rb

@@ -21,16 +21,37 @@ module SimpleConnect
         @event_keys   = event_keys&.map(&:to_s)&.freeze
       end
 
-      def deliver(event_key, fields = {}, event_id: nil, language: DEFAULT_LANGUAGE, occurred_at: nil, **extra_fields)
+      # 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[:name]` is always
+      # set to `event_key` — passing one is ignored.
+      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
 
-        merged_fields = stringify_keys(fields).merge(stringify_keys(extra_fields))
-        body = build_body(event_key, merged_fields, event_id: event_id, language: language, occurred_at: occurred_at)
+        body = build_body(event_key, recipient: recipient, event: stringify_keys(event))
         attach_response(@request.post(@endpoint_uri, body: body), Responses::DeliverResponse)
       end
 
@@ -46,14 +67,21 @@ module SimpleConnect
         URI.parse("#{@endpoint_uri}/#{URI.encode_www_form_component(event_id.to_s)}")
       end
 
-      def build_body(event_key, fields, event_id:, language:, occurred_at:)
+      def build_body(event_key, recipient:, event:)
         envelope = {
-          "event" => event_key,
-          "event_id" => resolve_event_id(event_id),
-          "occurred_at" => format_timestamp(occurred_at),
-          "language" => resolve_language(language)
+          "event_id"    => resolve_event_id(event["event_id"]),
+          "name"        => event_key,
+          "occurred_at" => format_timestamp(event["occurred_at"]),
+          "language"    => resolve_language(event["language"])
         }
-        envelope.merge(stringify_keys(fields)).to_json
+
+        {
+          "recipient" => {
+            "name"      => recipient["name"].to_s,
+            "mobile_no" => recipient["mobile_no"].to_s
+          },
+          "event" => event.merge(envelope)
+        }.to_json
       end
 
       def resolve_event_id(value)

data/lib/simple_connect/client.rb

@@ -4,7 +4,7 @@ module SimpleConnect
   # Entry point for the SimpleWaConnect integration client. Assembles the
   # signed-request transport once, then exposes two resource objects:
   #
-  #   SIMPLECONNECT.events.deliver(event_key, fields, event_id: ...)
+  #   SIMPLECONNECT.events.deliver(event_key, recipient: { mobile_no: }, event: { ... })
   #   SIMPLECONNECT.events.detail(event_id)
   #   SIMPLECONNECT.integrations.verify
   #

data/lib/simple_connect/responses/deliver_response.rb

@@ -5,14 +5,32 @@ module SimpleConnect
     # Wraps the `events.deliver` acknowledgement.
     #
     # Server returns:
-    #   202 on a new event → { status, log_id, event_id }
-    #   200 on an idempotent replay → { status, log_id, event_id, duplicate: true }
+    #   202 on a new event       → { status, log_id, event_id, event_log, message }
+    #   200 on a duplicate replay → { status, log_id, event_id, event_log, message, duplicate: true }
     # Either code is a success; consumers check `#duplicate?` to distinguish.
     # If the request was signed with a recently-rotated previous secret, the
     # server adds `"used_previous_secret": true` at the top level — a hint
     # to rotate credentials before the grace window ends.
+    #
+    # As of server v0.3.0, the response also carries the persisted
+    # event-log row + symmetric message under the same `event_log` /
+    # `message` keys that `events.detail` uses, so the same `EventResponse`
+    # parser wraps both. `#event` returns that wrapped row — the caller can
+    # read `#event.status`, `#event.error_text`, `#event.skipped?`, etc., to
+    # see at a glance whether the event was actually queued for dispatch
+    # (`"received"`) or skipped because the integration is paused / the
+    # per-event flow is disabled. Without this, a paused integration looked
+    # identical to a live one from the sender's perspective.
+    #
+    # `#event.message` is almost always `nil` at deliver time — dispatch is
+    # async and the outbound Message does not exist yet at the moment of
+    # the ack; populated only on duplicate replays of an already-dispatched
+    # event.
+    #
+    # The flat `#log_id` / `#event_id` accessors are preserved for backward
+    # compatibility.
     class DeliverResponse
-      attr_reader :status, :log_id, :event_id
+      attr_reader :status, :log_id, :event_id, :event
 
       def initialize(json)
         @json                 = json.is_a?(Hash) ? json : {}
@@ -21,6 +39,7 @@ module SimpleConnect
         @event_id             = @json["event_id"]
         @duplicate            = @json["duplicate"] == true
         @used_previous_secret = @json["used_previous_secret"] == true
+        @event                = @json["event_log"].is_a?(Hash) ? EventResponse.new(@json) : nil
       end
 
       def duplicate?

data/lib/simple_connect/responses/event_response.rb

@@ -2,9 +2,15 @@
 
 module SimpleConnect
   module Responses
-    # Wraps the `events.detail` success payload. Holds the event-log row
-    # and, optionally, a nested `MessageResponse` if a WhatsApp message is
-    # linked to the event.
+    # Wraps the persisted event-log row and (optionally) the linked
+    # WhatsApp message. Returned from two endpoints:
+    #
+    #   * `events.detail` — the full GET payload, where the server wraps
+    #     the log under an `"event_log"` key alongside `"message"`.
+    #   * `events.deliver` (server ≥ 0.3.0) — the same shape, embedded
+    #     under the `"event"` key on the deliver ack so callers know
+    #     immediately whether the event was queued (`"received"`) or
+    #     skipped (`"skipped_paused"`, `"skipped_disabled"`, …).
     class EventResponse
       attr_reader :event_id, :event_key, :status, :occurred_at, :created_at,
                   :updated_at, :error_text, :payload, :message

data/lib/simple_connect/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleConnect
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_connect-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ramkrishan Patidar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake