simple_connect-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1ab061c2118ee363fa9fdc9c1f69518a247cf55297d5b8dbf0de893c3507823
-  data.tar.gz: ce307f5e3403aead072705a621115308a573da3839bf5121b2e80b14a40503bc
+  metadata.gz: 3a7ccdbb67c4b168087543c5244805676d3e81d7b4522396047828cba666a56a
+  data.tar.gz: 723170ac99fdd68572c96d883337ef29715fca4741997d65b2b4a53827595ac3
 SHA512:
-  metadata.gz: cdc8f0ea63a0d3a133a871e0a0cd9ab21649d70ece906e1b54a14f7f36254186e80a5015e4890e12d9b4fdb673e89cb6a29aa941708e2c73bdef60761a7ed996
-  data.tar.gz: f800d93c034416cd8b143283f8fe9a354bc768e932f7ad399476e0ee134599adedaf59c7cec3ccd04ff330253bab4efae2ade766a0d879f6bb45cd301dddf35d
+  metadata.gz: 71a6195f53d733026560728f7c1d93774c5aa196ec54400fad876296ff387d59000166d0141e5a3a6eb661a813e0c09f2e76bf90b87bd156670f965291cfe513
+  data.tar.gz: bb9c5d523968ae07cf3306dab93a2302f389bac9992dac0bee67b37693b06222aa1562fdc46f230db251c97d99a535f8d6566510101ecc53621f489b90e878bf

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +51,6 @@ 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.2.0...HEAD
+[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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleConnect
-  VERSION = "0.1.0"
+  VERSION = "0.2.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.2.0
 platform: ruby
 authors:
 - Ramkrishan Patidar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake