simple_connect-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1ab061c2118ee363fa9fdc9c1f69518a247cf55297d5b8dbf0de893c3507823
+  data.tar.gz: ce307f5e3403aead072705a621115308a573da3839bf5121b2e80b14a40503bc
+SHA512:
+  metadata.gz: cdc8f0ea63a0d3a133a871e0a0cd9ab21649d70ece906e1b54a14f7f36254186e80a5015e4890e12d9b4fdb673e89cb6a29aa941708e2c73bdef60761a7ed996
+  data.tar.gz: f800d93c034416cd8b143283f8fe9a354bc768e932f7ad399476e0ee134599adedaf59c7cec3ccd04ff330253bab4efae2ade766a0d879f6bb45cd301dddf35d

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-20
+
+### Added
+
+- Initial public release.
+- `SimpleConnect::Client` — entry point with two resource objects:
+  - `events.deliver(event_key, fields, event_id:, language:, occurred_at:)` — POST a signed domain event.
+  - `events.detail(event_id)` — GET a previously-ingested event.
+  - `integrations.verify` — GET the status endpoint (derived by swapping `/events` → `/status`).
+- HMAC-SHA256 signing via three headers: `X-SimpleConnect-Key-Id`, `X-SimpleConnect-Timestamp`, `X-SimpleConnect-Signature`.
+- `User-Agent` header (`simple_connect-client/<version> ruby/<version>`) with optional `user_agent:` override.
+- Typed response classes under `SimpleConnect::Responses::`:
+  - `DeliverResponse`, `EventResponse`, `VerifyResponse`, `MessageResponse` for 2xx success shapes.
+  - `ErrorResponse` for 4xx / 5xx bodies (universal across endpoints).
+- Polymorphic `Result#data` — endpoint-specific success class on 2xx, `ErrorResponse` on 4xx/5xx with JSON body, `nil` on non-JSON or network errors.
+- `Result` as an immutable `Data.define` value type (not a mutable Struct) — consumers cannot mutate post-construction.
+- Library-level retry via `SimpleConnect::Retryable` — default 3 attempts with linear backoff on 5xx and network errors. Configurable via `max_attempts:` (simple) or `retryable:` (power-user policy injection). Mutually exclusive.
+- Optional client-side event-key whitelist via `event_keys:` — opt-in validation before the HTTP call. Without it, the server is the source of truth.
+- Error hierarchy under `SimpleConnect::Error`: `ConfigurationError`, `UnknownEventError`, `MalformedResponseError`.
+
+### Compatibility
+
+- Ruby 3.2+.
+- No runtime gem dependencies (stdlib only).
+
+[unreleased]: https://github.com/GemsEssence/SimpleWaConnect/compare/simple_connect-client-v0.1.0...HEAD
+[0.1.0]: https://github.com/GemsEssence/SimpleWaConnect/releases/tag/simple_connect-client-v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramkrishan Patidar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,337 @@
+# 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.
+
+Stdlib-only at runtime: no Rails, no Faraday, no gems.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "simple_connect-client", require: "simple_connect"
+```
+
+Then `bundle install`.
+
+## Setup
+
+Create one client per app (typically in an initializer):
+
+```ruby
+# config/initializers/simple_connect.rb
+SIMPLECONNECT = SimpleConnect::Client.new(
+  endpoint_url: ENV.fetch("SIMPLECONNECT_ENDPOINT_URL"), # e.g. https://app.simplewaconnect.com/api/v1/integrations/purepani/events
+  key_id:       ENV.fetch("SIMPLECONNECT_KEY_ID"),       # the "wa_sec_…" prefix shown on the integration Security card
+  secret:       ENV.fetch("SIMPLECONNECT_SECRET"),       # the raw signing secret shown once at connect / rotation
+  logger:       Rails.logger                             # optional
+)
+```
+
+One `Client` instance is safe to share across threads.
+
+### Optional: client-side event-key whitelist
+
+The gem ships no hardcoded event list — each provider owns its own taxonomy.
+By default, `events.deliver` accepts any non-empty `event_key` and the server
+validates it (returning 422 on unknown keys).
+
+If you'd rather catch typos before any HTTP call, pass `event_keys:`:
+
+```ruby
+SIMPLECONNECT = SimpleConnect::Client.new(
+  endpoint_url: "...",
+  key_id:       "...",
+  secret:       "...",
+  event_keys: %w[
+    customer_payment_received
+    customer_invoice_ready
+    customer_invoice_payment_reminder
+    customer_today_order_delivered
+    customer_app_invitation
+  ]
+)
+
+SIMPLECONNECT.events.deliver("customer_paymnet_received", ...) # typo
+# => ArgumentError: Unknown event_key 'customer_paymnet_received'.
+#    Must be one of: customer_payment_received, customer_invoice_ready, ...
+```
+
+Leave `event_keys:` unset when your provider's event taxonomy changes often,
+or when you'd rather rely on a single source of truth (the server).
+
+## Usage
+
+The client groups calls into two resource objects — `events` and `integrations`.
+
+### Deliver a domain event
+
+```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
+)
+```
+
+Pass an explicit `event_id:` (unique per domain event) for safe retries —
+duplicate event_ids are treated as no-ops by the server.
+
+### Fetch a previously-ingested event
+
+```ruby
+result = SIMPLECONNECT.events.detail("pp_payment_42")
+# result.response_body is JSON (see server docs for shape)
+```
+
+### Verify integration health
+
+```ruby
+result = SIMPLECONNECT.integrations.verify
+# result.response_body contains the per-event-flow snapshot
+```
+
+## Return value — `SimpleConnect::Result`
+
+Every resource call returns a `Result` struct with:
+
+| Field          | Type     | Notes                                                                                    |
+| -------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `success?`     | Boolean  | `true` on 2xx                                                                            |
+| `status_code`  | Integer  | HTTP status, or 0 on network error                                                       |
+| `response_body`| String?  | Raw body string (nil on network error)                                                   |
+| `error`        | String?  | Short error description on failure                                                       |
+| `attempts`     | Integer  | HTTP attempts made (1..MAX_ATTEMPTS)                                                     |
+| `data`         | Response?| Typed response object (see below) when the body was parseable; `nil` otherwise          |
+
+```ruby
+result = SIMPLECONNECT.events.deliver("customer_payment_received", fields)
+if result.success?
+  Rails.logger.info("delivered in #{result.attempts} attempt(s); id=#{result.data.event_id}")
+else
+  Rails.logger.error("deliver failed: #{result.error}")
+end
+```
+
+## Working with responses
+
+`result.data` is polymorphic by outcome — typed to whatever the server sent:
+
+| Outcome                              | `result.data`                                                     |
+| ------------------------------------ | ----------------------------------------------------------------- |
+| 2xx + valid JSON                     | endpoint-specific success class (see below)                       |
+| 4xx / 5xx + valid JSON               | `SimpleConnect::Responses::ErrorResponse`                         |
+| 4xx / 5xx + non-JSON body            | `nil` (fall back to `result.error` + `result.response_body`)      |
+| Network error (timeout, DNS, refused)| `nil`                                                             |
+| 2xx + unparseable JSON (server bug)  | raises `SimpleConnect::MalformedResponseError`                    |
+
+Always check `result.success?` first, then read `result.data`.
+
+### `events.deliver` → `DeliverResponse`
+
+```ruby
+result = SIMPLECONNECT.events.deliver(
+  "customer_payment_received", fields, event_id: "pp_pay_42"
+)
+
+if result.success?
+  response = result.data
+  response.event_id                # => "pp_pay_42"
+  response.log_id                  # => 42
+  response.duplicate?              # => false on fresh POST, true on idempotent replay
+  response.used_previous_secret?   # => true during the 24h grace window after rotation
+end
+```
+
+### `events.detail(event_id)` → `EventResponse`
+
+```ruby
+result = SIMPLECONNECT.events.detail("pp_pay_42")
+
+if result.success?
+  event = result.data
+  event.event_key           # => "customer_payment_received"
+  event.dispatched?         # => true / false
+  event.failed?             # => true / false
+  event.skipped?            # => true when status starts with "skipped_"
+  event.occurred_at         # => Time, or nil if unparseable
+  event.payload             # => original envelope hash (minus top-level metadata)
+  event.error_text          # => nil on success statuses; populated when status == "failed"
+
+  if event.message?
+    msg = event.message     # => MessageResponse (see below)
+    msg.incoming?           # => true for user-initiated inbound messages
+    msg.status_callback?    # => true for message.status callbacks
+    msg.message_id          # => "wamid.HBgL..."
+    msg.status              # => "delivered" / "read" / ...
+    msg.timestamp           # => Time (or nil if unparseable)
+  end
+end
+```
+
+### `integrations.verify` → `VerifyResponse`
+
+```ruby
+result = SIMPLECONNECT.integrations.verify
+
+if result.success?
+  verify = result.data
+  verify.connected?              # => true
+  verify.provider                # => "purepani"
+
+  verify.event_flows.each do |flow|
+    flow.event_key               # => "customer_payment_received"
+    flow.state                   # => "enabled" / "not_configured" / "needs_attention" / ...
+    flow.enabled?                # => true / false
+    flow.needs_attention?        # => true / false
+    flow.configured?             # => true when a template is linked
+
+    if flow.configured?
+      flow.template.name         # => "pay_rcvd"
+      flow.template.language     # => "en"
+      flow.template.approved?    # => true / false
+    end
+  end
+
+  # Lookup by event_key:
+  flow = verify.event_flow("customer_payment_received")
+end
+```
+
+### Error path → `ErrorResponse`
+
+```ruby
+result = SIMPLECONNECT.events.deliver("some_event", fields)
+
+unless result.success?
+  if result.data                 # ErrorResponse (or nil for non-JSON / network errors)
+    Rails.logger.warn("deliver rejected: #{result.data.message}")
+    # result.data.to_h → full parsed error body for any un-surfaced fields
+  else
+    # Network error or non-JSON body from a proxy.
+    Rails.logger.error("deliver transport-failed: #{result.error}")
+  end
+end
+```
+
+### Unsurfaced fields — `#to_h` escape hatch
+
+Every response class exposes `#to_h` returning a duplicate of the raw parsed
+JSON. If the server adds a new field we haven't surfaced as a method yet,
+reach for it via `response.to_h["new_field"]` instead of waiting for a gem
+release.
+
+## Run in a background job
+
+HTTP delivery is synchronous and may retry (up to 3 attempts, linear backoff).
+Wrap `events.deliver` in ActiveJob / Sidekiq so the calling request isn't
+blocked on endpoint latency.
+
+**Recommended — disable library retries when wrapping in a job queue.** The
+queue has its own retry layer; keeping both means one 500 becomes dozens of
+HTTP calls (job retries × library retries). Pass `max_attempts: 1` to the
+Client so each job invocation does a single POST:
+
+```ruby
+# config/initializers/simple_connect.rb
+SIMPLECONNECT = SimpleConnect::Client.new(
+  endpoint_url: ENV.fetch("SIMPLECONNECT_ENDPOINT_URL"),
+  key_id:       ENV.fetch("SIMPLECONNECT_KEY_ID"),
+  secret:       ENV.fetch("SIMPLECONNECT_SECRET"),
+  logger:       Rails.logger,
+  max_attempts: 1                # Sidekiq / ActiveJob will retry for us
+)
+
+class DeliverSimpleConnectEventJob < ApplicationJob
+  def perform(event_key, fields, event_id:)
+    SIMPLECONNECT.events.deliver(event_key, fields, event_id: event_id)
+  end
+end
+
+DeliverSimpleConnectEventJob.perform_later(
+  "customer_payment_received",
+  { customer_name: "...", ... },
+  event_id: "pp_payment_#{payment.id}"
+)
+```
+
+If you're *not* wrapping in a queue — e.g., calling from a one-off script or
+a synchronous backend — leave the default (`max_attempts: 3`, linear 1s/2s
+backoff, retries on 5xx and network errors).
+
+### Custom retry policy
+
+For exponential backoff, jitter, or a longer window, pass a `Retryable`
+instance instead. `max_attempts:` and `retryable:` are mutually exclusive.
+
+```ruby
+SimpleConnect::Client.new(
+  endpoint_url: ..., key_id: ..., secret: ...,
+  retryable: SimpleConnect::Retryable.new(
+    max_attempts: 5,
+    delay: ->(n) { (2**n) + rand }   # exponential + jitter
+  )
+)
+```
+
+## Error hierarchy
+
+All gem-specific errors inherit from `SimpleConnect::Error < StandardError`:
+
+| Error class                                | Raised when                                                                     |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| `SimpleConnect::ConfigurationError`        | `Client.new` is given blank/conflicting config.                                 |
+| `SimpleConnect::UnknownEventError`         | `events.deliver` called with a key outside the configured `event_keys:` list.   |
+| `SimpleConnect::MalformedResponseError`    | A 2xx response body wasn't valid JSON (server bug — not retryable).             |
+| `ArgumentError` (stdlib, not in hierarchy) | Programmer misuse: empty `event_key`, empty `event_id`, bad HTTP method, etc.   |
+
+## Signing scheme
+
+The client signs every request:
+
+- `X-SimpleConnect-Key-Id`    — the `key_id` passed to the client
+- `X-SimpleConnect-Timestamp` — current unix time in seconds
+- `X-SimpleConnect-Signature` — `sha256=<hex>` where `<hex>` is
+  HMAC-SHA256 of `"{timestamp}.{raw_body}"` using the secret.
+
+For GET requests (no body), the signed string is `"{timestamp}."` (timestamp
++ dot + empty body).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec                               # run the spec suite
+bundle exec rubocop --config .rubocop.yml       # lint (the --config flag is needed when the gem is developed inside a parent Rails app with its own .rubocop.yml)
+bundle exec rake build                          # build the .gem into pkg/
+bin/console                                     # IRB with the gem preloaded
+```
+
+## Contributing
+
+Bug reports and pull requests welcome on GitHub at the repo URL in the
+gemspec. Please:
+
+1. Fork and create a feature branch.
+2. Add or update specs for anything you change in `lib/`. The spec suite
+   should stay green across Ruby 3.2, 3.3, and 3.4 — CI runs the matrix.
+3. Run `bundle exec rubocop --config .rubocop.yml` and fix offenses before
+   opening the PR.
+4. Update `CHANGELOG.md` under `[Unreleased]`.
+5. Keep the gem dependency-free (stdlib only). New runtime deps need a
+   compelling reason and a discussion on the issue tracker first.
+
+Don't include unrelated refactors in the same PR — separate concerns land
+more predictably.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/simple_connect/api/events.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Api
+    # 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.
+    class Events
+      include ResponseAttachment
+
+      DEFAULT_LANGUAGE = "en"
+
+      def initialize(request:, endpoint_uri:, event_keys: nil)
+        @request      = request
+        @endpoint_uri = endpoint_uri
+        @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)
+        event_key = event_key.to_s
+        raise ArgumentError, "event_key is required" if event_key.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)
+        attach_response(@request.post(@endpoint_uri, body: body), Responses::DeliverResponse)
+      end
+
+      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
+
+      private
+
+      def detail_uri(event_id)
+        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:)
+        envelope = {
+          "event" => event_key,
+          "event_id" => resolve_event_id(event_id),
+          "occurred_at" => format_timestamp(occurred_at),
+          "language" => resolve_language(language)
+        }
+        envelope.merge(stringify_keys(fields)).to_json
+      end
+
+      def resolve_event_id(value)
+        v = value.to_s.strip
+        v.empty? ? "evt_#{SecureRandom.hex(8)}" : v
+      end
+
+      def resolve_language(value)
+        v = value.to_s.strip
+        v.empty? ? DEFAULT_LANGUAGE : v
+      end
+
+      def format_timestamp(value)
+        value ||= Time.now
+        value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+      end
+
+      def stringify_keys(hash)
+        return {} if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/simple_connect/api/integrations.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Api
+    # Integrations resource. Holds the shared Request and the endpoint URI;
+    # exposes #verify (GET the status endpoint, derived by swapping the
+    # trailing "/events" segment of the endpoint URL with "/status").
+    class Integrations
+      include ResponseAttachment
+
+      EVENTS_PATH_SUFFIX = "/events"
+      STATUS_PATH_SUFFIX = "/status"
+
+      def initialize(request:, endpoint_uri:)
+        @request      = request
+        @endpoint_uri = endpoint_uri
+      end
+
+      def verify
+        attach_response(@request.get(status_uri), Responses::VerifyResponse)
+      end
+
+      private
+
+      def status_uri
+        @status_uri ||= URI.parse(@endpoint_uri.to_s.sub(/#{Regexp.escape(EVENTS_PATH_SUFFIX)}\z/, STATUS_PATH_SUFFIX))
+      end
+    end
+  end
+end

data/lib/simple_connect/api/response_attachment.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Api
+    # Shared private helper for Api::Events and Api::Integrations. Parses the
+    # response body and returns a new Result with `.data` populated:
+    #   2xx + valid JSON   → the caller-supplied success class
+    #   4xx/5xx + valid JSON → Responses::ErrorResponse
+    #   nil / empty body   → returned unchanged (data stays nil)
+    #   4xx/5xx + non-JSON → returned unchanged (data stays nil)
+    #   2xx + unparseable JSON → raises MalformedResponseError (server bug)
+    #
+    # Result is immutable (Data.define); this helper builds a new Result via
+    # `#with_data` rather than mutating the original.
+    module ResponseAttachment
+      private
+
+      def attach_response(result, success_klass)
+        return result if result.response_body.nil? || result.response_body.empty?
+
+        parsed = parse_json_body(result.response_body, on_success: result.success?)
+        return result if parsed.nil?
+
+        data = result.success? ? success_klass.new(parsed) : Responses::ErrorResponse.new(parsed)
+        result.with_data(data)
+      end
+
+      def parse_json_body(str, on_success:)
+        JSON.parse(str)
+      rescue JSON::ParserError
+        raise SimpleConnect::MalformedResponseError, "Unparseable JSON body: #{str[0, 120]}" if on_success
+
+        nil
+      end
+    end
+  end
+end

data/lib/simple_connect/client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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.detail(event_id)
+  #   SIMPLECONNECT.integrations.verify
+  #
+  # See README.md for usage, envelope format, and signing scheme.
+  class Client
+    DEFAULT_TIMEOUT = 10
+
+    attr_reader :events, :integrations
+
+    # @param endpoint_url [String] the integration events URL, e.g.
+    #   "https://app.simplewaconnect.com/api/v1/integrations/purepani/events".
+    # @param key_id [String] signing-secret prefix shown on the integration
+    #   Security card (the `wa_sec_…` string, NOT the raw secret).
+    # @param secret [String] raw signing secret shown once at connect /
+    #   rotation.
+    # @param timeout [Integer] HTTP read/open timeout in seconds.
+    # @param logger [#info, #warn, nil] optional logger for transport events.
+    # @param event_keys [Array<String>, nil] optional client-side whitelist of
+    #   event_keys. When nil (default), `events.deliver` accepts any non-empty
+    #   event_key and the server is the source of truth.
+    # @param max_attempts [Integer] total HTTP attempts (including the first).
+    #   Default 3. Pass `1` to disable library-level retries (appropriate when
+    #   wrapping in a job queue that has its own retry layer). Mutually
+    #   exclusive with `retryable:`.
+    # @param retryable [SimpleConnect::Retryable, nil] power-user escape
+    #   hatch for custom retry policy (exponential backoff, jitter, etc.).
+    #   Mutually exclusive with `max_attempts:`.
+    # @param user_agent [String, nil] override the default User-Agent header
+    #   (`simple_connect-client/<version> ruby/<version>`).
+    def initialize(endpoint_url:, key_id:, secret:,
+                   timeout: DEFAULT_TIMEOUT, logger: nil, event_keys: nil,
+                   max_attempts: nil, retryable: nil, user_agent: nil)
+      raise ConfigurationError, "endpoint_url is required" if endpoint_url.to_s.strip.empty?
+      raise ConfigurationError, "key_id is required"       if key_id.to_s.strip.empty?
+      raise ConfigurationError, "secret is required"       if secret.to_s.strip.empty?
+
+      if max_attempts && retryable
+        raise ConfigurationError,
+              "pass either `max_attempts:` or `retryable:`, not both"
+      end
+
+      endpoint_uri = URI.parse(endpoint_url)
+      request = Request.new(
+        headers: Headers.new(key_id: key_id, secret: secret, user_agent: user_agent),
+        timeout: timeout,
+        logger: logger,
+        retryable: retryable || Retryable.new(max_attempts: max_attempts || Retryable::DEFAULT_MAX_ATTEMPTS)
+      )
+      @events       = Api::Events.new(request: request, endpoint_uri: endpoint_uri, event_keys: event_keys)
+      @integrations = Api::Integrations.new(request: request, endpoint_uri: endpoint_uri)
+    end
+  end
+end

data/lib/simple_connect/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Base class for all gem-specific errors. Inherits from StandardError so
+  # a plain `rescue` catches them.
+  class Error < StandardError; end
+
+  # Raised when `Client.new` is given missing or conflicting configuration
+  # (empty endpoint_url/key_id/secret, both `max_attempts:` and `retryable:`
+  # at once, etc.).
+  class ConfigurationError < Error; end
+
+  # Raised when `events.deliver` is called with an event_key that's not in
+  # the caller's `event_keys:` whitelist. Only fires when the whitelist is
+  # configured; without a whitelist, the server is the source of truth and
+  # validation is skipped.
+  class UnknownEventError < Error; end
+
+  # Raised when a 2xx response body cannot be parsed as JSON. Signals a
+  # server bug (the endpoint promised JSON but returned something else) —
+  # retrying won't help. On 4xx/5xx with an unparseable body, the parse is
+  # silently skipped and `Result#data` stays nil.
+  class MalformedResponseError < Error; end
+end

data/lib/simple_connect/headers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Builds the signed request headers (Content-Type + User-Agent + key id +
+  # timestamp + HMAC signature) for a given body. One instance per Client;
+  # holds the key_id and secret so callers never see them.
+  class Headers
+    KEY_ID_HEADER    = "X-SimpleConnect-Key-Id"
+    TIMESTAMP_HEADER = "X-SimpleConnect-Timestamp"
+    SIGNATURE_HEADER = "X-SimpleConnect-Signature"
+
+    def self.default_user_agent
+      "simple_connect-client/#{SimpleConnect::VERSION} ruby/#{RUBY_VERSION}"
+    end
+
+    def initialize(key_id:, secret:, user_agent: nil)
+      @key_id     = key_id.to_s
+      @secret     = secret.to_s
+      @user_agent = (user_agent || self.class.default_user_agent).to_s
+    end
+
+    def build_for(body)
+      timestamp = Time.now.to_i.to_s
+      {
+        "Content-Type" => "application/json",
+        "User-Agent" => @user_agent,
+        KEY_ID_HEADER => @key_id,
+        TIMESTAMP_HEADER => timestamp,
+        SIGNATURE_HEADER => "sha256=#{compute_signature(timestamp, body)}"
+      }
+    end
+
+    private
+
+    def compute_signature(timestamp, body)
+      OpenSSL::HMAC.hexdigest("sha256", @secret, "#{timestamp}.#{body}")
+    end
+  end
+end

data/lib/simple_connect/request.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Transport layer. Holds the Headers + retry policy + timeout/logger, and
+  # exposes #get / #post which return an immutable Result. Retries are
+  # delegated to the injected Retryable; per-retry sleep / delay policy lives
+  # there (see SimpleConnect::Retryable).
+  class Request
+    def initialize(headers:, timeout:, retryable:, logger: nil)
+      @headers   = headers
+      @timeout   = timeout
+      @logger    = logger
+      @retryable = retryable
+    end
+
+    def get(uri, body: "")
+      request_with_retry(http_method: :get, body: body, uri: uri)
+    end
+
+    def post(uri, body:)
+      request_with_retry(http_method: :post, body: body, uri: uri)
+    end
+
+    private
+
+    def request_with_retry(http_method:, body:, uri:)
+      @retryable.call(retriable_if: method(:retriable?)) do |attempt|
+        do_request(http_method: http_method, body: body, uri: uri, attempt: attempt)
+      end
+    end
+
+    def do_request(http_method:, body:, uri:, attempt:)
+      headers = @headers.build_for(body)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      request = build_net_http_request(http_method, uri, headers, body)
+
+      log(:info, "#{http_method.to_s.upcase} #{uri.host}#{uri.path} (#{body.bytesize}B signed body)")
+      response = http.request(request)
+      code = response.code.to_i
+      ok = (200..299).cover?(code)
+
+      log(ok ? :info : :warn, "Response #{code}")
+      Result.new(
+        success: ok,
+        status_code: code,
+        response_body: response.body,
+        error: ok ? nil : "HTTP #{code}: #{truncate(response.body)}",
+        attempts: attempt
+      )
+    rescue StandardError => e
+      log(:warn, "#{http_method.to_s.upcase} failed: #{e.class}: #{e.message}")
+      Result.new(
+        success: false,
+        status_code: 0,
+        response_body: nil,
+        error: "#{e.class}: #{e.message}",
+        attempts: attempt
+      )
+    end
+
+    def build_net_http_request(http_method, uri, headers, body)
+      case http_method
+      when :get
+        Net::HTTP::Get.new(uri.request_uri, headers)
+      when :post
+        Net::HTTP::Post.new(uri.request_uri, headers).tap { |r| r.body = body }
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{http_method.inspect}"
+      end
+    end
+
+    # Retry on network errors (status_code == 0) and 5xx. Never on 4xx — the
+    # server told us the request is bad; retrying won't help.
+    def retriable?(result)
+      result.status_code.zero? || (500..599).cover?(result.status_code)
+    end
+
+    def truncate(text, max = 300)
+      return "" if text.nil?
+
+      text.length > max ? "#{text[0, max]}…" : text
+    end
+
+    def log(level, message)
+      return unless @logger
+
+      @logger.public_send(level, "[SimpleConnect] #{message}")
+    rescue StandardError
+      # Never let logging break delivery.
+    end
+  end
+end

data/lib/simple_connect/responses/deliver_response.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Responses
+    # 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 }
+    # 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.
+    class DeliverResponse
+      attr_reader :status, :log_id, :event_id
+
+      def initialize(json)
+        @json                 = json.is_a?(Hash) ? json : {}
+        @status               = @json["status"]
+        @log_id               = @json["log_id"]
+        @event_id             = @json["event_id"]
+        @duplicate            = @json["duplicate"] == true
+        @used_previous_secret = @json["used_previous_secret"] == true
+      end
+
+      def duplicate?
+        @duplicate
+      end
+
+      def used_previous_secret?
+        @used_previous_secret
+      end
+
+      def to_h
+        @json.dup
+      end
+    end
+  end
+end

data/lib/simple_connect/responses/error_response.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Responses
+    # Wraps the JSON error body returned on 4xx / 5xx responses. Server error
+    # envelopes today are uniform (`{"error": "..."}` possibly with
+    # `{"success": false}`). If the server grows richer error shapes later,
+    # this class can be extended in place without adding per-endpoint
+    # error subclasses.
+    #
+    # Construction is defensive: a non-Hash argument, nil, or a Hash missing
+    # the "error" key all produce `message == ""` — never raises. Callers
+    # always have `result.error` (the short HTTP-level string) as a fallback.
+    class ErrorResponse
+      attr_reader :message
+
+      def initialize(json)
+        @json    = json.is_a?(Hash) ? json : {}
+        @message = @json["error"].to_s
+      end
+
+      def to_h
+        @json.dup
+      end
+    end
+  end
+end

data/lib/simple_connect/responses/event_response.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+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.
+    class EventResponse
+      attr_reader :event_id, :event_key, :status, :occurred_at, :created_at,
+                  :updated_at, :error_text, :payload, :message
+
+      def initialize(json)
+        @json                 = json.is_a?(Hash) ? json : {}
+        event_log             = @json["event_log"].is_a?(Hash) ? @json["event_log"] : {}
+        @event_id             = event_log["event_id"]
+        @event_key            = event_log["event_key"]
+        @status               = event_log["status"]
+        @occurred_at          = parse_time(event_log["occurred_at"])
+        @created_at           = parse_time(event_log["created_at"])
+        @updated_at           = parse_time(event_log["updated_at"])
+        @error_text           = event_log["error_text"]
+        @used_previous_secret = event_log["used_previous_secret"] == true
+        @payload              = event_log["payload"].is_a?(Hash) ? event_log["payload"] : {}
+        @message              = @json["message"] ? MessageResponse.new(@json["message"]) : nil
+      end
+
+      def dispatched?
+        @status == "dispatched"
+      end
+
+      def failed?
+        @status == "failed"
+      end
+
+      def skipped?
+        @status.to_s.start_with?("skipped")
+      end
+
+      def message?
+        !@message.nil?
+      end
+
+      def used_previous_secret?
+        @used_previous_secret
+      end
+
+      def to_h
+        @json.dup
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/simple_connect/responses/message_response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Responses
+    # Wraps a `message` block — returned nested inside an `EventResponse` or,
+    # when we add future endpoints that return message payloads, as a top-
+    # level response. Discriminated on the `event` field:
+    #   "message.status"   → status_callback?  (delivered / read / failed)
+    #   "message.incoming" → incoming?         (user-initiated inbound msg)
+    class MessageResponse
+      EVENT_STATUS   = "message.status"
+      EVENT_INCOMING = "message.incoming"
+
+      attr_reader :event, :data
+
+      def initialize(json)
+        @json  = json.is_a?(Hash) ? json : {}
+        @event = @json["event"]
+        @data  = @json["data"].is_a?(Hash) ? @json["data"] : {}
+      end
+
+      def status_callback?
+        @event == EVENT_STATUS
+      end
+
+      def incoming?
+        @event == EVENT_INCOMING
+      end
+
+      # Common fields pulled from `data` for convenience. Exact shape mirrors
+      # the outbound status callback — see SimpleWaConnect's status-callback
+      # docs for the full field list. Use `#data` or `#to_h` for anything
+      # not surfaced here.
+      def message_id
+        @data["message_id"]
+      end
+
+      def status
+        @data["status"]
+      end
+
+      def timestamp
+        parse_time(@data["timestamp"])
+      end
+
+      def recipient
+        @data["recipient"]
+      end
+
+      def to_h
+        @json.dup
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/simple_connect/responses/verify_response.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  module Responses
+    # Wraps the `integrations.verify` success payload. Exposes the integration
+    # metadata (provider, status) plus an array of `EventFlow` objects — one
+    # per event key the integration supports, with its enabled/attention state
+    # and (optional) linked template.
+    class VerifyResponse
+      attr_reader :provider, :status, :event_flows
+
+      def initialize(json)
+        @json        = json.is_a?(Hash) ? json : {}
+        integration  = @json["integration"].is_a?(Hash) ? @json["integration"] : {}
+        @provider    = integration["provider"]
+        @status      = integration["status"]
+        @event_flows = Array(@json["event_flows"]).map { |ef| EventFlow.new(ef) }
+      end
+
+      def connected?
+        @status == "connected"
+      end
+
+      def event_flow(event_key)
+        key = event_key.to_s
+        @event_flows.find { |f| f.event_key == key }
+      end
+
+      def to_h
+        @json.dup
+      end
+
+      # Per-event-key flow state. Mirrors one element of the server's
+      # `event_flows` array.
+      class EventFlow
+        attr_reader :event_key, :state, :template
+
+        def initialize(json)
+          json             = {} unless json.is_a?(Hash)
+          @event_key       = json["event_key"]
+          @state           = json["state"]
+          @enabled         = json["enabled"] == true
+          @needs_attention = json["needs_attention"] == true
+          @template        = json["template"] ? Template.new(json["template"]) : nil
+        end
+
+        def enabled?
+          @enabled
+        end
+
+        def needs_attention?
+          @needs_attention
+        end
+
+        def configured?
+          !@template.nil?
+        end
+
+        # The template linked to this event flow (nil if none assigned).
+        class Template
+          attr_reader :name, :language, :status
+
+          def initialize(json)
+            json      = {} unless json.is_a?(Hash)
+            @name     = json["name"]
+            @language = json["language"]
+            @status   = json["status"]
+          end
+
+          def approved?
+            @status == "approved"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simple_connect/result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Envelope returned from every resource method. Immutable value type
+  # (`Data.define`) — consumers cannot mutate it post-construction.
+  #
+  # Holds the HTTP-level outcome plus the typed response object (when the
+  # server body was parseable).
+  #
+  # `#data` is polymorphic by outcome:
+  # - 2xx + valid JSON → endpoint-specific success class (DeliverResponse, etc.)
+  # - 4xx/5xx + valid JSON → ErrorResponse
+  # - anything else (non-JSON body, network error) → nil
+  #
+  # Consumers always check `#success?` first, then read `#data` or fall back
+  # to `#error` + `#response_body`.
+  Result = Data.define(
+    :success, :status_code, :response_body, :error, :attempts, :data
+  ) do
+    # Defaults so internal construction sites don't have to pass every field.
+    def initialize(success:, status_code: 0, response_body: nil, error: nil, attempts: 1, data: nil)
+      super
+    end
+
+    def success?
+      success
+    end
+
+    def failed?
+      !success
+    end
+
+    # Returns a new Result with `data` replaced. Used by ResponseAttachment
+    # (Data instances are immutable; #with from Data.define creates a copy).
+    def with_data(new_data)
+      with(data: new_data)
+    end
+  end
+end

data/lib/simple_connect/retryable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SimpleConnect
+  # Library-level retry policy for transient transport failures (5xx, network
+  # errors). Lives next to `Request`; `Client.new(max_attempts: N)` is the
+  # ergonomic knob, and power users can pass a custom instance via
+  # `retryable:` for exponential backoff / jitter / caps.
+  #
+  # Use `max_attempts: 1` to disable retries entirely — appropriate when
+  # `events.deliver` is wrapped in a job queue (Sidekiq, ActiveJob) that has
+  # its own retry layer. Avoids double-retry math (1 job retry × 3 lib
+  # retries = 75 HTTP calls per logical failure).
+  class Retryable
+    DEFAULT_MAX_ATTEMPTS = 3
+
+    # @param max_attempts [Integer] total attempts (1 = no retries).
+    # @param delay [#call] lambda/proc taking the attempt number (1-indexed),
+    #   returning seconds to sleep before the next attempt. Default is
+    #   linear: 1s, 2s.
+    # @param sleep [#call] sleep function. Injectable for specs so the suite
+    #   doesn't actually wait.
+    def initialize(max_attempts: DEFAULT_MAX_ATTEMPTS, delay: ->(n) { n.to_f }, sleep: Kernel.method(:sleep))
+      raise ArgumentError, "max_attempts must be >= 1" if max_attempts < 1
+
+      @max_attempts = max_attempts
+      @delay        = delay
+      @sleep        = sleep
+    end
+
+    # Call the block up to `max_attempts` times. The block receives the
+    # 1-indexed attempt number and must return an object responding to
+    # `#success?`. `retriable_if` decides whether a failed result is
+    # retryable (5xx / network → yes; 4xx → no).
+    def call(retriable_if:)
+      attempt = 0
+      loop do
+        attempt += 1
+        result   = yield(attempt)
+        return result if result.success? || !retriable_if.call(result) || attempt >= @max_attempts
+
+        @sleep.call(@delay.call(attempt))
+      end
+    end
+  end
+end

data/lib/simple_connect/version.rb

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

data/lib/simple_connect.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+require_relative "simple_connect/version"
+require_relative "simple_connect/errors"
+require_relative "simple_connect/responses/error_response"
+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/result"
+require_relative "simple_connect/retryable"
+require_relative "simple_connect/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/client"
+
+# Top-level namespace. See SimpleConnect::Client for usage.
+module SimpleConnect
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: simple_connect-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ramkrishan Patidar
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.66'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.66'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+description: |
+  SimpleConnect::Client is a dependency-free (stdlib-only) 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 and network errors.
+email:
+- ram@gemsessence.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/simple_connect.rb
+- lib/simple_connect/api/events.rb
+- lib/simple_connect/api/integrations.rb
+- lib/simple_connect/api/response_attachment.rb
+- lib/simple_connect/client.rb
+- lib/simple_connect/errors.rb
+- lib/simple_connect/headers.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_response.rb
+- lib/simple_connect/responses/verify_response.rb
+- lib/simple_connect/result.rb
+- lib/simple_connect/retryable.rb
+- lib/simple_connect/version.rb
+homepage: https://github.com/GemsEssence/SimpleWaConnect/tree/main/gems/simple_connect-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/GemsEssence/SimpleWaConnect/tree/main/gems/simple_connect-client
+  source_code_uri: https://github.com/GemsEssence/SimpleWaConnect/tree/main/gems/simple_connect-client
+  changelog_uri: https://github.com/GemsEssence/SimpleWaConnect/blob/main/gems/simple_connect-client/CHANGELOG.md
+  bug_tracker_uri: https://github.com/GemsEssence/SimpleWaConnect/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Ruby client for SimpleWaConnect integration endpoints.
+test_files: []