simple_connect-client 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80608e802aa6273143cb24d056f08abc1541dac6223371eae39c2611ed2ab99e
-  data.tar.gz: 9c8e9130fd84bda6b19eaccf5f57a68ff81dc186070f19ef1834114981dbb8bb
+  metadata.gz: fecfb423740267511e5fe8cdabc01f99dae1394be3cd461ceaa0925b01bb8d9c
+  data.tar.gz: c132195a36db6b5b5025a328c7602bd855a9cb094ae692548d0325a6da3ef8a9
 SHA512:
-  metadata.gz: ad8d5b28164c2598aeb32ee7bf0db42eec12ab15a0fed501d12b4cd9e33dfda11ac69ae24e21be0def68773c1119c40d020d31c0e77aae5b993458a1cc02e7b9
-  data.tar.gz: 2d578d852fa29a83400e6fecd49918cbddc118ebe7e846f64496e04d79b88ea7c3d3844c4f6f2c22c55900085e3b6872c2b8cc1a0a04810cc9c5b1cc63abfd29
+  metadata.gz: bc2c72805d94ac74047a81ba8454ad2e6ee4fac20e016d7fc25682c8be81b09e183d7ee6f19a7fe2957652a3bdc792b7f13aee47a5ed5bf1063c9886f2636b89
+  data.tar.gz: dd5904e4da8281014d6412971838fccf1be64ce0d6c781ca54d201078045be27d1172d5d7db322a008b8fee3558bd1ceff61a3e95d33a83402e999b03529b013

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `SimpleConnect::MessagesClient` — a second, independently-constructible
+  entry point for sending WhatsApp **template messages** over the account
+  API. Built from `base_url:` + `api_key:` (no HMAC signing secret), so a
+  caller with only an account API key — and no integration — can use it.
+  Distinct from `SimpleConnect::Client`, which signs Events over HMAC. See
+  `docs/adr/0001-messages-use-separate-bearer-client.md`.
+- `messages.deliver(template_name:, recipients:, ...)` — sends one approved
+  template to one or many recipients. Optional `language_code:`,
+  `sender_phone_number:`, `header:`, `body:`, `buttons:`, and
+  `message_group:` are forwarded verbatim in the documented wire shape and
+  omitted from the request when not given. Returns a `Result` with a typed
+  `Responses::MessageDeliverResponse` (`#queued_messages`, `#errors`,
+  `#any_queued?`) on 2xx — partial success (some recipients queued, some
+  rejected) is preserved.
+- `messages.detail(message_id)` — GET a previously-sent message's delivery
+  status. Returns a `Result` with a typed `Responses::MessageDetailResponse`
+  (`#status`, `#recipient`, `#message_group`, `#error`, `#failed?`); `#error`
+  is nil unless the message failed.
+- `SimpleConnect::BearerHeaders` — `Authorization: Bearer <api_key>` header
+  builder. Shares the `Request` / `Retryable` / `Result` transport with the
+  HMAC path unchanged; performs no body signing.
+
+### Compatibility
+
+- Scope is **template messages only** — free-form / session messages are not
+  supported (they require an open 24h window and are not exposed over the
+  JSON API).
+- Targets the existing `POST /api/v1/whatsapp_messages` and
+  `GET /api/v1/whatsapp_messages/:id` endpoints — no server changes required.
+- The HMAC Events path (`Client`, `events`, `integrations`) is untouched.
+
 ## [0.3.0] - 2026-04-30
 
 ### Added

data/README.md

@@ -1,9 +1,22 @@
 # simple_connect-client
 
-Dependency-free Ruby client for the **SimpleWaConnect** integration endpoints.
-Ships domain events (POST), fetches event details (GET), and verifies
-integration health — all signed with HMAC-SHA256, with built-in retries on
-5xx / network errors.
+Dependency-free Ruby client for the **SimpleWaConnect** API.
+
+Two independent entry points:
+
+- **`SimpleConnect::Client`** — the **integration** client. Ships domain
+  events (POST), fetches event details (GET), and verifies integration
+  health — all signed with HMAC-SHA256. For integration providers holding a
+  signing `key_id` / `secret`.
+- **`SimpleConnect::MessagesClient`** — the **messages** client. Sends
+  WhatsApp template messages (POST) and looks up their delivery status (GET)
+  — authenticated with a Bearer account **API key**. For any caller with an
+  API key, including third parties with no integration. See
+  [docs/adr/0001-messages-use-separate-bearer-client.md](docs/adr/0001-messages-use-separate-bearer-client.md)
+  for why these are separate clients.
+
+Both share the same transport: built-in retries on 5xx / network errors and
+the same `Result` contract.
 
 Stdlib-only at runtime: no Rails, no Faraday, no gems.
 
@@ -114,6 +127,96 @@ result = SIMPLECONNECT.integrations.verify
 # result.response_body contains the per-event-flow snapshot
 ```
 
+## Sending template messages
+
+`MessagesClient` is a **separate client** from the HMAC `Client` above. It
+authenticates with a Bearer account **API key** (`sk_live_…`) and sends
+**template messages only** — free-form / session messages are out of scope
+(they require an open 24-hour window and aren't exposed over the JSON API).
+
+### Setup
+
+```ruby
+MESSAGES = SimpleConnect::MessagesClient.new(
+  base_url: ENV.fetch("SIMPLECONNECT_BASE_URL"), # e.g. https://app.simplewaconnect.com
+  api_key:  ENV.fetch("SIMPLECONNECT_API_KEY"),  # account API key, "sk_live_…"
+  logger:   Rails.logger                          # optional
+)
+```
+
+The instance is immutable and thread-safe — share one per `api_key`. If you
+send on behalf of multiple accounts (each with its own number / API key),
+construct one `MessagesClient` per `api_key` and memoize them.
+
+### Deliver a template message
+
+```ruby
+result = MESSAGES.messages.deliver(
+  template_name: "order_update",
+  language_code: "en_US",                                  # optional → template default
+  recipients: [
+    { mobile_no: "919999999999", name: "John Doe" }        # 1..N recipients; mobile_no required
+  ],
+  sender_phone_number: "919000000001",                     # optional → account's first active number
+  header:  { text: ["Order Update"] },                     # forwarded verbatim (see below)
+  body:    ["John", "ORDER-101"],                          # positional array OR named hash
+  buttons: [
+    { index: 2, sub_type: "url", parameters: [{ type: "text", text: "ORDER-101" }] }
+  ],
+  message_group: "order-101"                               # optional correlation id
+)
+
+if result.success?
+  response = result.data                  # MessageDeliverResponse
+  response.queued_messages                # => [{ "message_id" =>, "recipient" =>, "status" => }]
+  response.errors                         # => per-recipient rejections, if any
+  response.any_queued?                    # => true when at least one recipient was enqueued
+else
+  Rails.logger.warn("send rejected: #{result.data&.message || result.error}")
+end
+```
+
+`template_name` and `recipients` are validated client-side (blank/empty raise
+`ArgumentError` before any HTTP call); each recipient needs `mobile_no`.
+Everything else — template existence, the 24-hour window, opt-out, sender
+validity — is server-authoritative.
+
+**Components are forwarded verbatim** in the shape the message API documents.
+Pick the `header` / `body` / `buttons` shape based on the approved template:
+
+- `header:` — one of `{ text: [...] }` / `{ text: { name: val } }` /
+  `{ image: { link:, caption: } }` / `{ video: {...} }` /
+  `{ document: { link:, filename: } }` / `{ audio: { link: } }` /
+  `{ location: { latitude:, longitude:, name:, address: } }`. Omit if the
+  template has no header (or a text header with no variables).
+- `body:` — positional `["v1", "v2"]` or named `{ customer_name: "John" }`,
+  matching the template's `parameter_format`. Omit if no body variables.
+- `buttons:` — only for buttons carrying runtime values (dynamic URL suffix,
+  copy-code). Each entry needs `index` (0-based) and `sub_type`.
+
+Any argument left `nil` is omitted from the request entirely.
+
+### Look up a message's status
+
+```ruby
+result = MESSAGES.messages.detail(message_id)
+
+if result.success?
+  msg = result.data            # MessageDetailResponse
+  msg.status                   # => "queued" / "sent" / "delivered" / "read" / "failed" / ...
+  msg.recipient                # => "919999999999"
+  msg.message_group            # => "order-101" (or nil)
+  if msg.failed?
+    msg.error                  # => { "message" => "...", "data" => { ... } }
+  end
+end
+```
+
+Like the Events client, message-sending HTTP is synchronous and may retry —
+wrap it in a background job and pass `max_attempts: 1` to avoid stacking the
+queue's retries on the library's (see "Run in a background job" below; the
+same guidance applies to `MessagesClient`).
+
 ## Return value — `SimpleConnect::Result`
 
 Every resource call returns a `Result` struct with:

data/lib/simple_connect/api/messages.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Api
+    # Messages resource. Sends WhatsApp template messages over Bearer auth via
+    # the account API (POST /api/v1/whatsapp_messages). Holds the shared
+    # Request and the base URI (host); owns the fixed endpoint path.
+    class Messages
+      include ResponseAttachment
+
+      MESSAGES_PATH         = "/api/v1/whatsapp_messages"
+      MESSAGE_TYPE_TEMPLATE = "template"
+
+      def initialize(request:, base_uri:)
+        @request  = request
+        @base_uri = base_uri
+      end
+
+      def deliver(template_name:, recipients:, language_code: nil, sender_phone_number: nil,
+                  header: nil, body: nil, buttons: nil, message_group: nil)
+        raise ArgumentError, "template_name is required" if template_name.to_s.strip.empty?
+
+        entry = {
+          "message_type" => MESSAGE_TYPE_TEMPLATE,
+          "template_name" => template_name,
+          "recipients" => normalize_recipients(recipients),
+          "language_code" => language_code,
+          "sender_phone_number" => sender_phone_number,
+          "header" => header,
+          "body" => body,
+          "buttons" => buttons,
+          "message_group" => message_group
+        }.compact
+
+        payload = { "messages" => [entry] }.to_json
+        attach_response(@request.post(collection_uri, body: payload), Responses::MessageDeliverResponse)
+      end
+
+      def detail(message_id)
+        raise ArgumentError, "message_id is required" if message_id.to_s.strip.empty?
+
+        attach_response(@request.get(member_uri(message_id)), Responses::MessageDetailResponse)
+      end
+
+      private
+
+      def collection_uri
+        @collection_uri ||= URI.join(@base_uri.to_s, MESSAGES_PATH)
+      end
+
+      def member_uri(message_id)
+        URI.join(@base_uri.to_s, "#{MESSAGES_PATH}/#{URI.encode_www_form_component(message_id.to_s)}")
+      end
+
+      def normalize_recipients(recipients)
+        raise ArgumentError, "recipients must be a non-empty array" unless recipients.is_a?(Array) && recipients.any?
+
+        recipients.map do |recipient|
+          row = stringify_keys(recipient)
+          raise ArgumentError, "mobile_no is required for each recipient" if row["mobile_no"].to_s.strip.empty?
+
+          row
+        end
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/simple_connect/bearer_headers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Builds Bearer-auth request headers (Content-Type + User-Agent +
+  # Authorization) for the account Message API. Same #build_for(body)
+  # interface as Headers, so Request can use either interchangeably — but
+  # this one performs no body signing. One instance per MessagesClient; holds
+  # the api_key so callers never see it.
+  class BearerHeaders
+    def initialize(api_key:, user_agent: nil)
+      @api_key    = api_key.to_s
+      @user_agent = (user_agent || Headers.default_user_agent).to_s
+    end
+
+    def build_for(_body)
+      {
+        "Content-Type" => "application/json",
+        "User-Agent" => @user_agent,
+        "Authorization" => "Bearer #{@api_key}"
+      }
+    end
+  end
+end

data/lib/simple_connect/messages_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Entry point for the account Message API. Assembles the Bearer-auth
+  # transport once, then exposes a single resource object:
+  #
+  #   MSG = SimpleConnect::MessagesClient.new(base_url:, api_key:)
+  #   MSG.messages.deliver(template_name:, recipients:, ...)
+  #
+  # Distinct from SimpleConnect::Client (which signs Events over HMAC): a
+  # caller holding only an account api_key — with no integration — uses this.
+  # See docs/adr/0001-messages-use-separate-bearer-client.md.
+  class MessagesClient
+    DEFAULT_TIMEOUT = 10
+
+    attr_reader :messages
+
+    # @param base_url [String] the app host, e.g.
+    #   "https://app.simplewaconnect.com". The fixed message path is appended
+    #   by the resource.
+    # @param api_key [String] account API key (`sk_live_…`) sent as a Bearer
+    #   token.
+    # @param timeout [Integer] HTTP read/open timeout in seconds.
+    # @param logger [#info, #warn, nil] optional logger for transport events.
+    # @param max_attempts [Integer] total HTTP attempts (including the first).
+    #   Default 3. Pass `1` to disable library retries. Mutually exclusive
+    #   with `retryable:`.
+    # @param retryable [SimpleConnect::Retryable, nil] custom retry policy.
+    #   Mutually exclusive with `max_attempts:`.
+    # @param user_agent [String, nil] override the default User-Agent header.
+    def initialize(base_url:, api_key:,
+                   timeout: DEFAULT_TIMEOUT, logger: nil,
+                   max_attempts: nil, retryable: nil, user_agent: nil)
+      raise ConfigurationError, "base_url is required" if base_url.to_s.strip.empty?
+      raise ConfigurationError, "api_key is required"  if api_key.to_s.strip.empty?
+
+      if max_attempts && retryable
+        raise ConfigurationError,
+              "pass either `max_attempts:` or `retryable:`, not both"
+      end
+
+      base_uri = URI.parse(base_url)
+      request = Request.new(
+        headers: BearerHeaders.new(api_key: api_key, user_agent: user_agent),
+        timeout: timeout,
+        logger: logger,
+        retryable: retryable || Retryable.new(max_attempts: max_attempts || Retryable::DEFAULT_MAX_ATTEMPTS)
+      )
+      @messages = Api::Messages.new(request: request, base_uri: base_uri)
+    end
+  end
+end

data/lib/simple_connect/responses/message_deliver_response.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Responses
+    # Wraps the `messages.deliver` acknowledgement.
+    #
+    # Server returns (200, or 422 when nothing queued):
+    #   { "success": true,
+    #     "queued_messages": [{ "message_id":, "recipient":, "status": }],
+    #     "errors": [ ... ] }
+    #
+    # Partial success is possible — some recipients queued, some rejected —
+    # so consumers read both `#queued_messages` and `#errors`.
+    class MessageDeliverResponse
+      attr_reader :queued_messages, :errors
+
+      def initialize(json)
+        @json            = json.is_a?(Hash) ? json : {}
+        @queued_messages = @json["queued_messages"] || []
+        @errors          = @json["errors"] || []
+      end
+
+      def any_queued?
+        @queued_messages.any?
+      end
+
+      def to_h
+        @json.dup
+      end
+    end
+  end
+end

data/lib/simple_connect/responses/message_detail_response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Responses
+    # Wraps the `messages.detail` lookup (GET /api/v1/whatsapp_messages/:id).
+    #
+    # Server returns:
+    #   { "message_id":, "status":, "message_group":, "recipient": }
+    # plus, only when the message failed:
+    #   "error": { "message":, "data": }
+    #
+    # `#error` is nil unless the message failed; `#failed?` reflects that.
+    class MessageDetailResponse
+      attr_reader :message_id, :status, :recipient, :message_group, :error
+
+      def initialize(json)
+        @json          = json.is_a?(Hash) ? json : {}
+        @message_id    = @json["message_id"]
+        @status        = @json["status"]
+        @recipient     = @json["recipient"]
+        @message_group = @json["message_group"]
+        @error         = @json["error"]
+      end
+
+      def failed?
+        !@error.nil?
+      end
+
+      def to_h
+        @json.dup
+      end
+    end
+  end
+end

data/lib/simple_connect/version.rb

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

data/lib/simple_connect.rb

@@ -14,14 +14,19 @@ require_relative "simple_connect/responses/message_response"
 require_relative "simple_connect/responses/event_response"
 require_relative "simple_connect/responses/verify_response"
 require_relative "simple_connect/responses/deliver_response"
+require_relative "simple_connect/responses/message_deliver_response"
+require_relative "simple_connect/responses/message_detail_response"
 require_relative "simple_connect/result"
 require_relative "simple_connect/retryable"
 require_relative "simple_connect/headers"
+require_relative "simple_connect/bearer_headers"
 require_relative "simple_connect/request"
 require_relative "simple_connect/api/response_attachment"
 require_relative "simple_connect/api/events"
 require_relative "simple_connect/api/integrations"
+require_relative "simple_connect/api/messages"
 require_relative "simple_connect/client"
+require_relative "simple_connect/messages_client"
 
 # Top-level namespace. See SimpleConnect::Client for usage.
 module SimpleConnect

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_connect-client
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ramkrishan Patidar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-30 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -83,14 +83,19 @@ files:
 - lib/simple_connect.rb
 - lib/simple_connect/api/events.rb
 - lib/simple_connect/api/integrations.rb
+- lib/simple_connect/api/messages.rb
 - lib/simple_connect/api/response_attachment.rb
+- lib/simple_connect/bearer_headers.rb
 - lib/simple_connect/client.rb
 - lib/simple_connect/errors.rb
 - lib/simple_connect/headers.rb
+- lib/simple_connect/messages_client.rb
 - lib/simple_connect/request.rb
 - lib/simple_connect/responses/deliver_response.rb
 - lib/simple_connect/responses/error_response.rb
 - lib/simple_connect/responses/event_response.rb
+- lib/simple_connect/responses/message_deliver_response.rb
+- lib/simple_connect/responses/message_detail_response.rb
 - lib/simple_connect/responses/message_response.rb
 - lib/simple_connect/responses/verify_response.rb
 - lib/simple_connect/result.rb