jamm 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17f04171e0380f881d022d968eafaecfab7de2ca6e0a91ed56b217a4434afcab
-  data.tar.gz: 2f98a4766f79146afc5a839a26b2f69674ac87330065f663d9c90441a52b5f74
+  metadata.gz: f15af21a2f10a3f3ea2c5636349ab7449d90997795bb8e9a729d063a02c70040
+  data.tar.gz: 48f9b4782863261fb11c8ce3e37f5f0819c8b87d24136c595df7396a0cbfd3b5
 SHA512:
-  metadata.gz: 1182b1fc82f6d8c009e9f98542baf35e2b4542ff81f8b49ba4de35319662a8a2bcec5e47f35b2f45041a491f4d9c7697997259263426960d11493cefa0eef547
-  data.tar.gz: a17d3a2f3a352b39a8c2021593dc24e4d960afd460bc2ecdea038186b078e9df92d8b6e6b0e9965995cf50408c1327eef01dbd3ffd39909aa222636e8155b337
+  metadata.gz: 18be3aac7a0654593d068e7e8f7c889e02d6df8bf66bd6c00d024fd15aeff33f4611055a902f223f4fdfcb7e6dd518c0a3c27659bf79a9f030bcb39846ed9c54
+  data.tar.gz: 214589958f50dda8837dbc9d27017597fb9d88f10ee02923eee15ff278b6b1d5e7f809412dd0c5a6b475a936de575fff6f69c19949a4dec8fa06efcc41baccd2

data/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-07-22
+
+### Fixed
+
+- Restored the forward-compatible `Jamm::Webhook.parse` first shipped in 2.3.0 (2.4.0 and 2.5.0 regressed to strict parsing):
+  - Webhook parsing no longer fails on new fields added by the backend (unknown fields are ignored instead of raising `ArgumentError`)
+  - Numeric enum wire values (`status`, …) resolve onto their string enum constants, matching REST API responses
+  - Refund webhooks expose the nested transaction fields, the refund's `rfd-` id (`refund_id` and `refund.id`), and typed nested models (`refund.error.code` works instead of raising `NoMethodError`)
+  - `EVENT_TYPE_USER_ACCOUNT_DELETED` webhooks parse (previously raised `Unknown event type`)
+  - `Webhook.parse` accepts payloads with either string or symbol keys
+- `Webhook.parse` routes on the coerced event type, so event routing also survives a numeric `event_type` wire value
+
+## [2.5.0] - 2026-07-03
+
+### Added
+
+- Added `Jamm::Webhook.verify_and_parse(raw_body)` — verifies the HMAC signature over the exact received `content` bytes and parses in one step. Unlike `Jamm::Webhook.verify`, it is not broken by JSON re-serialization (correctly handles `&`, `<`, `>` in content) and rejects bodies with duplicate top-level keys.
+
 ## [2.4.0] - 2026-07-01
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jamm (2.4.0)
+    jamm (2.6.0)
       base64 (~> 0.2)
       rest-client (~> 2.0)
       typhoeus (~> 1.0, >= 1.0.1)
@@ -24,9 +24,7 @@ GEM
       ffi (>= 1.15.0)
     faker (3.5.1)
       i18n (>= 1.8.11, < 2)
-    ffi (1.17.0-aarch64-linux-gnu)
-    ffi (1.17.0-arm64-darwin)
-    ffi (1.17.0-x86_64-linux-gnu)
+    ffi (1.17.0)
     gimei (1.5.0)
     hashdiff (1.1.0)
     http-accept (1.7.0)

data/jamm.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
 
   s.files = `git ls-files`.split("\n").reject do |file|
     file.start_with?(
+      'compatibility',
       'examples',
       'images',
       'openapi',

data/lib/jamm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jamm
-  VERSION = '2.4.0'
+  VERSION = '2.6.0'
 end

data/lib/jamm/webhook.rb

@@ -11,39 +11,160 @@ module Jamm
     # Parse command is for parsing the received webhook message.
     # It does not call anything remotely, instead returns the suitable object.
     def self.parse(json)
-      out = Jamm::OpenAPI::MerchantWebhookMessage.new(json)
+      # Webhook payloads may arrive with string or symbol keys depending on how
+      # the caller decoded the JSON (e.g. JSON.parse with or without
+      # symbolize_names: true). Normalize to symbols so event-type routing,
+      # wrapper flattening, and field lookups are reliable either way.
+      json = deep_symbolize_keys(json)
 
-      case json[:event_type]
-      when Jamm::OpenAPI::EventType::CHARGE_CREATED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+      out = build(Jamm::OpenAPI::MerchantWebhookMessage, json)
 
-      when Jamm::OpenAPI::EventType::CHARGE_UPDATED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      # Route on the coerced event type: the wire value is an enum string today,
+      # but `build` also resolves a numeric wire value onto its string constant,
+      # so routing survives either serialization.
+      case out.event_type
+      when Jamm::OpenAPI::EventType::CHARGE_CREATED,
+           Jamm::OpenAPI::EventType::CHARGE_UPDATED,
+           Jamm::OpenAPI::EventType::REFUND_SUCCEEDED,
+           Jamm::OpenAPI::EventType::REFUND_FAILED,
+           Jamm::OpenAPI::EventType::CHARGE_SUCCESS,
+           Jamm::OpenAPI::EventType::CHARGE_FAIL
+        out.content = build(Jamm::OpenAPI::ChargeMessage, flatten_charge_content(json[:content]))
         return out
 
-      when Jamm::OpenAPI::EventType::REFUND_SUCCEEDED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      when Jamm::OpenAPI::EventType::CONTRACT_ACTIVATED
+        out.content = build(Jamm::OpenAPI::ContractMessage, json[:content])
         return out
 
-      when Jamm::OpenAPI::EventType::REFUND_FAILED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      when Jamm::OpenAPI::EventType::USER_ACCOUNT_DELETED
+        out.content = build(Jamm::OpenAPI::UserAccountMessage, json[:content])
         return out
+      end
 
-      when Jamm::OpenAPI::EventType::CHARGE_SUCCESS
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+      raise 'Unknown event type'
+    end
 
-      when Jamm::OpenAPI::EventType::CHARGE_FAIL
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+    # Build a generated model from a webhook payload while normalizing the
+    # quirks of the webhook wire format. Applied to every model, so charges,
+    # contracts, user-account and refund messages all benefit:
+    #
+    #   1. Forward-compat: the Jamm backend can add new fields to webhook
+    #      payloads at any time. The generated model `initialize` raises
+    #      ArgumentError on any key outside `attribute_map`, so unknown keys are
+    #      dropped first. Known keys are snake_case, matching `attribute_map`.
+    #   2. Numeric enums: the backend serializes webhook payloads with Go's
+    #      `json.Marshal` (not protojson), so every enum field (status,
+    #      api_source, ...) arrives as its integer value, while the generated
+    #      enums are string-based. Each integer is mapped back to the enum string
+    #      so it matches the values returned by the REST API.
+    #   3. Nested models: the generated `initialize` assigns nested objects
+    #      verbatim (the `_deserialize` coercion only runs from `build_from_hash`,
+    #      which expects camelCase keys the webhook does not use). So a nested
+    #      field like `refund.error` would stay a raw Hash and `error.code` would
+    #      raise NoMethodError. We coerce nested model fields (and arrays of them)
+    #      recursively so the typed accessors work.
+    def self.build(klass, attributes)
+      return nil if attributes.nil?
 
-      when Jamm::OpenAPI::EventType::CONTRACT_ACTIVATED
-        out.content = Jamm::OpenAPI::ContractMessage.new(json[:content])
-        return out
+      known = klass.attribute_map
+      types = klass.openapi_types
+      filtered = attributes.each_with_object({}) do |(key, value), acc|
+        sym = key.to_sym
+        next unless known.key?(sym)
+
+        acc[sym] = coerce(types[sym], value)
       end
 
-      raise 'Unknown event type'
+      klass.new(filtered)
+    end
+
+    # Refund webhooks (REFUND_SUCCEEDED / REFUND_FAILED) deliver `content` as a
+    # nested { transaction, refund } wrapper instead of a flat ChargeMessage.
+    # Flatten it back into a ChargeMessage so callers always receive the same shape.
+    def self.flatten_charge_content(content)
+      return content unless content.is_a?(Hash) && content.key?(:transaction)
+
+      refund = content[:refund]
+      # Keep `refund` as the raw Hash: `build` coerces it into a typed RefundInfo
+      # (and recursively types its nested `error`). Also surface the refund's
+      # `rfd-` id on the flat `refund_id` attribute the model documents.
+      charge = content[:transaction].merge(refund: refund)
+      charge[:refund_id] = refund[:id] if refund.is_a?(Hash) && !refund[:id].nil?
+      charge
+    end
+
+    # Coerce a raw webhook value into the shape the generated model expects,
+    # based on the field's openapi type: numeric enums become their string
+    # constant, nested models become typed instances, and `Array<T>` elements are
+    # coerced by `T`. Anything else passes through untouched.
+    def self.coerce(type, value)
+      return value if value.nil?
+
+      inner = array_inner_type(type)
+      return coerce_array(inner, value) unless inner.nil?
+
+      klass = openapi_const(type)
+      return value if klass.nil?
+
+      if klass.respond_to?(:all_vars)
+        resolve_enum(klass, value)
+      elsif klass.respond_to?(:openapi_types) && value.is_a?(Hash)
+        build(klass, value)
+      else
+        value
+      end
+    end
+
+    # Coerce each element of an `Array<T>` field by its inner type `T`.
+    def self.coerce_array(inner_type, value)
+      return value unless value.is_a?(Array)
+
+      value.map { |element| coerce(inner_type, element) }
+    end
+
+    # Extract `T` from an `Array<T>` openapi type, or nil when not an array type.
+    def self.array_inner_type(type)
+      match = type.to_s.match(/\AArray<(.+)>\z/)
+      match && match[1]
+    end
+
+    # Map a numeric enum wire value onto its string enum constant. A value that
+    # is already a string (REST-style) passes through untouched.
+    def self.resolve_enum(enum, value)
+      return value unless value.is_a?(Integer)
+
+      vars = enum.all_vars
+      # Guard the bounds explicitly: Ruby maps negative indices from the end of
+      # the array, so any unexpected wire value must fall back to the *_UNSPECIFIED
+      # member (index 0) rather than silently selecting the wrong constant.
+      value.between?(0, vars.length - 1) ? vars[value] : vars[0]
+    end
+
+    # Resolve an openapi_types entry (e.g. :ChargeMessageApiSource, :RefundInfo)
+    # to its generated class, or nil when the type is a primitive (String,
+    # Integer, ...) or otherwise unresolvable.
+    def self.openapi_const(type)
+      return nil if type.nil?
+
+      name = type.to_s
+      return nil unless Jamm::OpenAPI.const_defined?(name)
+
+      Jamm::OpenAPI.const_get(name)
+    rescue NameError
+      nil
+    end
+
+    # Recursively convert Hash keys to symbols so parsing is robust regardless of
+    # how the caller decoded the webhook JSON.
+    def self.deep_symbolize_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = deep_symbolize_keys(v) }
+      when Array
+        value.map { |v| deep_symbolize_keys(v) }
+      else
+        value
+      end
     end
 
     # Verify message.
@@ -63,6 +184,118 @@ module Jamm
       raise Jamm::InvalidSignatureError, 'Digests do not match'
     end
 
+    # Verify the HMAC signature over the exact received bytes and parse, in one step.
+    #
+    # This is the recommended entry point. The backend signs the raw +content+ bytes it
+    # transmits, produced by Go's JSON encoder which HTML-escapes & < > as & <
+    # >. Re-serializing the parsed content (as +verify+ does via JSON.dump) un-escapes
+    # those characters, so its digest no longer matches. This slices the raw +content+
+    # substring out of +raw_body+ verbatim and HMACs that.
+    def self.verify_and_parse(raw_body)
+      raise ArgumentError, 'raw_body cannot be nil or empty' if raw_body.nil? || raw_body.empty?
+
+      parsed = JSON.parse(raw_body, symbolize_names: true)
+      signature = parsed[:signature]
+      raise ArgumentError, "Webhook body is missing the 'signature' field" if signature.nil? || signature.empty?
+
+      raw_content = extract_raw_content(raw_body)
+      digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), Jamm.client_secret, raw_content)
+      given = "sha256=#{digest}"
+      raise Jamm::InvalidSignatureError, 'Digests do not match' unless secure_compare(given, signature)
+
+      parse(parsed)
+    end
+
+    # Extracts the top-level +content+ value substring from a raw webhook body verbatim,
+    # without decoding or re-serializing it, so the exact signed bytes are recovered.
+    def self.extract_raw_content(raw_body)
+      i = 0
+      n = raw_body.length
+      i += 1 while i < n && raw_body[i].match?(/\s/)
+      raise ArgumentError, 'Webhook body must be a JSON object' unless raw_body[i] == '{'
+
+      i += 1
+      # Scan every top-level key. Duplicate keys are rejected: JSON.parse keeps the LAST
+      # occurrence while this returns the FIRST, so a duplicate `content` could otherwise
+      # verify one payload and parse another (signature bypass).
+      seen = {}
+      content = nil
+      loop do
+        i += 1 while i < n && (raw_body[i].match?(/\s/) || raw_body[i] == ',')
+        break if i >= n || raw_body[i] == '}'
+        raise ArgumentError, 'Malformed webhook JSON' unless raw_body[i] == '"'
+
+        key_start = i
+        i = skip_string(raw_body, i)
+        # Decode the key (not a raw slice): otherwise an escaped duplicate such as
+        # "content" would evade both the duplicate check and the 'content' match below,
+        # while JSON.parse collapses it to `content` and keeps the last value. Normalize a
+        # malformed key to ArgumentError to match the rest of this method.
+        key = begin
+          JSON.parse(raw_body[key_start...i])
+        rescue JSON::ParserError
+          raise ArgumentError, 'Malformed webhook JSON'
+        end
+        raise ArgumentError, "Duplicate top-level key in webhook body: #{key}" if seen.key?(key)
+
+        seen[key] = true
+        i += 1 while i < n && raw_body[i].match?(/\s/)
+        raise ArgumentError, 'Malformed webhook JSON' unless raw_body[i] == ':'
+
+        i += 1
+        i += 1 while i < n && raw_body[i].match?(/\s/)
+        value_start = i
+        i = skip_value(raw_body, i)
+        content = raw_body[value_start...i] if key == 'content'
+      end
+      raise ArgumentError, "Webhook body does not contain 'content' field" if content.nil?
+
+      content
+    end
+
+    # +i+ points at an opening '"'. Returns the index just past the closing '"'.
+    def self.skip_string(str, i)
+      i += 1
+      n = str.length
+      while i < n
+        c = str[i]
+        if c == '\\'
+          i += 2
+          next
+        end
+        return i + 1 if c == '"'
+
+        i += 1
+      end
+      raise ArgumentError, 'Unterminated string in webhook JSON'
+    end
+
+    # +i+ points at the first char of a JSON value. Returns the index just past it.
+    def self.skip_value(str, i)
+      return skip_string(str, i) if str[i] == '"'
+
+      if str[i] == '{' || str[i] == '['
+        depth = 0
+        n = str.length
+        while i < n
+          ch = str[i]
+          if ch == '"'
+            i = skip_string(str, i)
+            next
+          elsif ch == '{' || ch == '['
+            depth += 1
+          elsif ch == '}' || ch == ']'
+            depth -= 1
+            return i + 1 if depth.zero?
+          end
+          i += 1
+        end
+        raise ArgumentError, 'Unterminated object/array in webhook JSON'
+      end
+      i += 1 while i < str.length && !",}] \t\n\r".include?(str[i])
+      i
+    end
+
     # Securely compare two strings of equal length.
     # This method is a port of ActiveSupport::SecurityUtils.secure_compare
     # which works on non-Rails platforms.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jamm
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Jamm
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -72,32 +72,6 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- compatibility/.gitignore
-- compatibility/1.3.0/Gemfile
-- compatibility/1.3.0/compat_test.rb
-- compatibility/1.4.0/Gemfile
-- compatibility/1.4.0/compat_test.rb
-- compatibility/1.4.1/Gemfile
-- compatibility/1.4.1/compat_test.rb
-- compatibility/1.5.0/Gemfile
-- compatibility/1.5.0/compat_test.rb
-- compatibility/1.6.0/Gemfile
-- compatibility/1.6.0/compat_test.rb
-- compatibility/1.7.0/Gemfile
-- compatibility/1.7.0/compat_test.rb
-- compatibility/2.0.0/Gemfile
-- compatibility/2.0.0/compat_test.rb
-- compatibility/2.1.0/Gemfile
-- compatibility/2.1.0/compat_test.rb
-- compatibility/2.2.0/Gemfile
-- compatibility/2.2.0/compat_test.rb
-- compatibility/2.3.0/Gemfile
-- compatibility/2.3.0/compat_test.rb
-- compatibility/Makefile
-- compatibility/README.md
-- compatibility/shared/suite.rb
-- compatibility/templates/Gemfile.tmpl
-- compatibility/templates/compat_test.rb.tmpl
 - jamm.gemspec
 - lib/jamm.rb
 - lib/jamm/api.rb

data/compatibility/.gitignore

@@ -1,11 +0,0 @@
-# Per-version status emitted by `make report` for the PR comment workflow.
-compat-report.tsv
-
-# Installed published gems and per-directory bundler state -- pulled fresh from
-# the registry per run.
-*/.bundle
-*/vendor
-
-# Lockfiles are intentionally untracked: these install real published versions
-# from the registry and are out of scope for our vulnerability checks.
-*/Gemfile.lock

data/compatibility/1.3.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.3.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '1.3.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/1.3.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.3.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@1.3.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '1.3.0'
-end

data/compatibility/1.4.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.4.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '1.4.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/1.4.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.4.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@1.4.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '1.4.0'
-end

data/compatibility/1.4.1/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.4.1` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '1.4.1'
-gem 'test-unit', '~> 3.0'

data/compatibility/1.4.1/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.4.1` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@1.4.1 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '1.4.1'
-end

data/compatibility/1.5.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.5.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '1.5.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/1.5.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.5.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@1.5.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '1.5.0'
-end

data/compatibility/1.6.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.6.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '1.6.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/1.6.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.6.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@1.6.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '1.6.0'
-end

data/compatibility/1.7.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.7.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '1.7.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/1.7.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=1.7.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@1.7.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '1.7.0'
-end

data/compatibility/2.0.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.0.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '2.0.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/2.0.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.0.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@2.0.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '2.0.0'
-end

data/compatibility/2.1.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.1.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '2.1.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/2.1.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.1.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@2.1.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '2.1.0'
-end

data/compatibility/2.2.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.2.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '2.2.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/2.2.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.2.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@2.2.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '2.2.0'
-end

data/compatibility/2.3.0/Gemfile

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.3.0` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '2.3.0'
-gem 'test-unit', '~> 3.0'

data/compatibility/2.3.0/compat_test.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=2.3.0` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@2.3.0 (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '2.3.0'
-end

data/compatibility/Makefile

@@ -1,63 +0,0 @@
-.PHONY: ls install test report clean add
-
-WORKDIR := /services/packages/sdk/ruby/compatibility
-
-# Run inside the api container (same pattern as the parent SDK Makefile) so the
-# SDK's env: 'local' host (api.jamm.test) resolves to the local backend.
-ifneq ($(WORKDIR), $(PWD))
-EXEC := docker compose exec -w $(WORKDIR) api
-endif
-
-# Pinned version directories -- everything except shared/ and templates/.
-VERSIONS := $(filter-out shared/ templates/,$(wildcard */))
-
-# List the version directories under test.
-ls:
-	@echo "Compat versions:" $(VERSIONS:/=)
-
-# Install each pinned gem version into its own bundle (lockfiles are gitignored
-# on purpose). BUNDLE_GEMFILE scopes bundler to that directory's Gemfile.
-install:
-	@$(EXEC) bash -c 'set -e; for d in $(VERSIONS); do \
-		echo "== install $$d =="; \
-		( cd $$d && BUNDLE_GEMFILE=Gemfile bundle install ); \
-	done'
-
-# Run the shared suite against every pinned version. Runs all versions even if
-# one fails, then exits non-zero if any did -- so a single broken version is
-# visible without masking the rest.
-test:
-	@$(EXEC) bash -c 'rc=0; for d in $(VERSIONS); do \
-		echo "== test $$d =="; \
-		( cd $$d && \
-			MERCHANT_CLIENT_ID=$(MERCHANT_CLIENT_ID) \
-			MERCHANT_CLIENT_SECRET=$(MERCHANT_CLIENT_SECRET) \
-			BUNDLE_GEMFILE=Gemfile bundle exec ruby compat_test.rb ) || rc=1; \
-	done; exit $$rc'
-
-# CI variant of `test`: runs every version, writes per-version status to
-# compat-report.tsv ("<version>\t<PASS|FAIL>"), and always exits 0. The
-# workflow turns the file into a PR comment, so the merge is not blocked when
-# an older published version is out of sync with the current API.
-report:
-	@$(EXEC) bash -c 'rm -f compat-report.tsv; for d in $(VERSIONS); do \
-		v=$${d%/}; \
-		echo "== test $$v =="; \
-		if ( cd $$d && \
-			MERCHANT_CLIENT_ID=$(MERCHANT_CLIENT_ID) \
-			MERCHANT_CLIENT_SECRET=$(MERCHANT_CLIENT_SECRET) \
-			BUNDLE_GEMFILE=Gemfile bundle exec ruby compat_test.rb ); then status=PASS; else status=FAIL; fi; \
-		printf "%s\t%s\n" "$$v" "$$status" >> compat-report.tsv; \
-	done; echo "== summary =="; cat compat-report.tsv'
-
-# Remove installed bundles and lockfiles for every version.
-clean:
-	@for d in $(VERSIONS); do rm -rf $$d/.bundle $$d/vendor $$d/Gemfile.lock; done
-
-# Scaffold a new version directory from the templates: make add VER=2.4.0
-add:
-	@test -n "$(VER)" || { echo "usage: make add VER=x.y.z"; exit 1; }
-	@mkdir -p "$(VER)"
-	@sed 's/__VERSION__/$(VER)/g' templates/Gemfile.tmpl        > "$(VER)/Gemfile"
-	@sed 's/__VERSION__/$(VER)/g' templates/compat_test.rb.tmpl > "$(VER)/compat_test.rb"
-	@echo "Created $(VER)/ -- run 'make install' then 'make test'."

data/compatibility/README.md

@@ -1,119 +0,0 @@
-# Ruby SDK backward-compatibility tests
-
-This directory verifies that previously **published** versions of the `jamm` gem
-still work against the current API — i.e. that the SDKs and the backend stay in
-sync. The pre-release/latest SDK lives in `../lib` and is covered by
-`../test.e2e`; this directory covers the **released** versions pulled from the
-RubyGems registry.
-
-## Layout
-
-```
-packages/sdk/
-  compatibility/
-    testdata/        # language-neutral backend webhook records; shared by every SDK harness
-  ruby/compatibility/
-    shared/
-      suite.rb         # the shared, capability-gated smoke suite (single source of truth)
-    templates/         # source templates for each version directory
-    <version>/
-      Gemfile          # pins jamm@<version> + test-unit
-      compat_test.rb   # thin shim: requires the pinned gem, runs the shared suite
-    Makefile
-```
-
-Each `<version>/` directory installs its own pinned gem into its own bundle, so
-its `compat_test.rb` requires `jamm` and bundler resolves it to that directory's
-version. The shim then mixes `JammCompat::Tests` into a `Test::Unit::TestCase`,
-so the **same** assertions run against every version.
-
-Lockfiles (`Gemfile.lock`) and installed bundles are git-ignored on purpose:
-these install real published versions from the registry and are out of scope for
-our vulnerability checks.
-
-## What is tested
-
-The suite is capability-gated, because the public surface grew over time. Where a
-service is missing in an older gem, its check is omitted (skipped) rather than
-failed:
-
-| Check                          | Touches API | Notes                                             |
-| ------------------------------ | ----------- | ------------------------------------------------- |
-| `Jamm.configure` + environment | no          | environment round-trips to `local`                |
-| `Jamm::Healthcheck.ping`       | yes         | skipped unless `MERCHANT_CLIENT_*` are set         |
-| `Jamm::Webhook.verify`         | no          | recomputes the HMAC signature; asserts the contract |
-| `Jamm::Webhook.parse`          | no          | forward-compat: parses backend records carrying newer fields (see below) |
-
-### Forward-compatibility: `Jamm::Webhook.parse` against current-day records
-
-`../../compatibility/testdata/*.json` are webhook payloads shaped as the backend
-sends them, covering both shapes the harness cares about:
-
-- `charge_success_api_source.json` — a flat charge carrying `api_source`
-  (`ChargeMessage` field 23). The backend marshals webhook content with Go's
-  `json.Marshal` (not `protojson`), so the enum goes out as its numeric value
-  (`"api_source": 3`); there is no enum-string form on the wire.
-- `refund_succeeded_nested_api_source.json` — the nested refund wrapper
-  (`content.transaction` + `content.refund`) **with** `api_source`.
-- `refund_succeeded_nested_no_api_source.json` — the same nested wrapper
-  **without** `api_source` (older backends, or charges created outside the charge
-  API), which must also parse, resolving to the model's default.
-
-The suite asserts every parse-capable version **must** decode the core
-`ChargeMessage` (`id`, `customer`) and ignore fields it predates. A version that
-*has* `parse` but throws on these records **fails** the test — that failure is the
-signal it is out of sync with the API, not an accepted outcome (mirrors the Node
-harness).
-
-> [!IMPORTANT]
-> The `api_source` / nested-refund webhook feature was **rolled back on `main`**
-> for release (PR #2316, reverting #2304/#2281/#2282/…). As of that revert the
-> backend does **not** emit `api_source` in charge webhooks and the latest SDK
-> source (`../lib`, currently `2.2.0`) has no forward-compat parse. These fixtures
-> are retained deliberately — covering both the with- and without-`api_source`
-> shapes — so this harness is the ready-made signal for which published versions
-> tolerate the contract once it re-lands.
-
-Expected behavior across the pinned versions, from each gem's CHANGELOG (the
-authoritative matrix is whatever `make test` reports against the installed gems):
-
-| version        | nested refund wrapper | `api_source` resolution | expected parse result                                  |
-| -------------- | --------------------- | ----------------------- | ------------------------------------------------------ |
-| 1.3.0 – 1.7.0  | no                    | no                      | refund events unhandled → `parse` raises (out of sync) |
-| 2.0.0 – 2.2.0  | partial               | no                      | strict decode throws on `api_source` (out of sync)     |
-| 2.3.0          | yes                   | yes                     | ✅ decodes core fields, ignores/resolves newer fields  |
-
-Verified locally: the suite passes 100% against a forward-compat-capable SDK
-source and fails the three `parse` fixtures against the reverted `2.2.0` source —
-i.e. the harness flags out-of-sync versions exactly as intended.
-
-## Running
-
-Pinned versions are installed from the registry; the live `healthcheck` check
-talks to the local backend (`api.jamm.test`), so the suite runs inside the `api`
-container like the parent SDK's e2e tests.
-
-```sh
-# from packages/sdk/ruby/compatibility
-make install                 # install all pinned versions
-make test \
-  MERCHANT_CLIENT_ID=...  \
-  MERCHANT_CLIENT_SECRET=... # run the suite against every version
-```
-
-Without credentials the offline checks still run and the live `healthcheck`
-check is skipped.
-
-## Pinned versions
-
-The latest 10 versions published to the RubyGems registry (the installable
-source of truth): `1.3.0, 1.4.0, 1.4.1, 1.5.0, 1.6.0, 1.7.0, 2.0.0, 2.1.0,
-2.2.0, 2.3.0`. The registry and the GitHub tags can disagree — pin to what
-RubyGems actually serves, since that is what merchants install.
-
-To add a newly released version:
-
-```sh
-make add VER=2.4.0           # scaffolds 2.4.0/ from templates/
-make install && make test
-```

data/compatibility/shared/suite.rb

@@ -1,146 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'openssl'
-require 'test/unit'
-
-# Shared backward-compatibility smoke suite for the published `jamm` gem.
-#
-# Each compatibility/<version>/ directory pins and installs its own published gem
-# version (via its sibling Gemfile), then its compat_test.rb shim builds a
-# Test::Unit::TestCase that `include`s JammCompat::Tests. Pinning happens through
-# bundler, so `require 'jamm'` in that process resolves to *this* directory's
-# version and the same assertions run against every version.
-#
-# The suite is capability-gated: the public surface grew across versions, so a
-# check for a service that did not exist yet is omitted (skipped) rather than
-# failed. The one deliberate exception is webhook.parse -- see PARSE_FIXTURES.
-module JammCompat
-  # Shared decoded-core assertions: every parse-capable version must decode these
-  # from each fixture regardless of the newer fields it carries.
-  EXPECTED = { id: 'trx-00000000000000000000', customer: 'cus-00000000000000000000' }.freeze
-
-  # Backend webhook records shaped exactly as the current API emits them (see
-  # packages/sdk/compatibility/testdata/), carrying fields newer than most published gems: api_source
-  # (ChargeMessage field 23) and the nested { transaction, refund } refund
-  # wrapper. The backend marshals webhook content with Go's json.Marshal (not
-  # protojson), so enums go out numeric ("api_source": 3) -- there is no
-  # enum-string form on the wire, so one fixture per record shape is enough.
-  # Each charge/refund shape is covered both with and without api_source so the
-  # post-revert backend (no api_source emitted) is exercised alongside the
-  # re-landed-feature shape.
-  PARSE_FIXTURES = [
-    { file: 'charge_success_api_source.json', event: 'CHARGE_SUCCESS + api_source' },
-    { file: 'charge_success_without_api_source.json', event: 'CHARGE_SUCCESS, no api_source' },
-    { file: 'refund_succeeded_nested_api_source.json', event: 'REFUND_SUCCEEDED, nested wrapper + api_source' },
-    { file: 'refund_succeeded_nested_no_api_source.json', event: 'REFUND_SUCCEEDED, nested wrapper, no api_source' }
-  ].freeze
-
-  # Payload for the webhook.verify contract check. The signature is NOT hardcoded:
-  # verify() HMAC-signs JSON.dump(data) with the configured client_secret, so the
-  # suite recomputes the expected signature for whatever secret it configured.
-  # Fixed pseudo IDs, not real merchant data.
-  WEBHOOK_DATA = {
-    customer: 'cus-000000000000000000',
-    created_at: '2024-11-29T02:16:12.168127Z',
-    activated_at: '2024-11-29T02:16:18.040142301Z',
-    merchant_name: 'TestMerchant1'
-  }.freeze
-
-  # Mirrors the e2e credential env vars. When unset, the live-API healthcheck is
-  # skipped so the offline checks still run (e.g. in CI without a reachable backend).
-  CLIENT_ID = ENV['MERCHANT_CLIENT_ID'] || 'compat-client-id'
-  CLIENT_SECRET = ENV['MERCHANT_CLIENT_SECRET'] || 'compat-client-secret'
-  HAS_API_CREDS = !(ENV['MERCHANT_CLIENT_ID'].to_s.empty? || ENV['MERCHANT_CLIENT_SECRET'].to_s.empty?)
-
-  # Fixtures live in the language-neutral packages/sdk/compatibility/testdata/
-  # directory so every SDK harness consumes the same backend records.
-  def self.testdata_path(file)
-    File.join(__dir__, '..', '..', '..', 'compatibility', 'testdata', file)
-  end
-
-  # The actual checks. A version directory's shim mixes this into a
-  # Test::Unit::TestCase, so test/unit auto-discovers every `test_*` method.
-  module Tests
-    def load_fixture(file)
-      JSON.parse(File.read(JammCompat.testdata_path(file)), symbolize_names: true)
-    end
-
-    def configure!
-      Jamm.configure(
-        client_id: JammCompat::CLIENT_ID,
-        client_secret: JammCompat::CLIENT_SECRET,
-        env: 'local'
-      )
-    end
-
-    # config -- expected in every published version.
-    def test_config_round_trips_local_environment
-      omit('Jamm.configure absent in this version') unless Jamm.respond_to?(:configure)
-      configure!
-      omit('Jamm.environment reader absent in this version') unless Jamm.respond_to?(:environment)
-      assert_equal('local', Jamm.environment)
-    end
-
-    # healthcheck -- hits the live local API (api.jamm.test), so it needs creds and
-    # a reachable backend; skipped otherwise.
-    def test_healthcheck_pings_api
-      unless defined?(Jamm::Healthcheck) && Jamm::Healthcheck.respond_to?(:ping)
-        omit('healthcheck service absent in this version')
-      end
-      omit('MERCHANT_CLIENT_* not set; live API check skipped') unless JammCompat::HAS_API_CREDS
-
-      configure!
-      res = Jamm::Healthcheck.ping
-      assert_not_nil(res)
-      assert_true(res.ok)
-    end
-
-    # webhook.verify -- offline signing-contract check: recompute the signature the
-    # SDK expects, confirm verify() accepts it, then confirm a tampered (but
-    # well-formed) signature is rejected.
-    def test_webhook_verify_accepts_valid_and_rejects_tampered
-      unless defined?(Jamm::Webhook) && Jamm::Webhook.respond_to?(:verify)
-        omit('webhook.verify absent in this version')
-      end
-
-      configure!
-      digest = OpenSSL::HMAC.hexdigest(
-        OpenSSL::Digest.new('sha256'),
-        JammCompat::CLIENT_SECRET,
-        JSON.dump(JammCompat::WEBHOOK_DATA)
-      )
-
-      assert_nothing_raised do
-        Jamm::Webhook.verify(data: JammCompat::WEBHOOK_DATA, signature: "sha256=#{digest}")
-      end
-
-      assert_raise do
-        Jamm::Webhook.verify(data: JammCompat::WEBHOOK_DATA, signature: "sha256=#{'0' * 64}")
-      end
-    end
-
-    # webhook.parse forward-compat -- pretends the backend is sending current-day
-    # records that carry api_source and the nested refund wrapper. Every
-    # parse-capable version MUST decode the core ChargeMessage and ignore fields it
-    # predates.
-    #
-    # NOTE: there is intentionally no rescue here. A version that *has* parse but
-    # throws on these records is out of sync with the API -- that failure is the
-    # signal, not an accepted outcome (mirrors the Node harness, where only the
-    # latest version passes). Only a version with no parse capability at all is
-    # omitted.
-    JammCompat::PARSE_FIXTURES.each do |fx|
-      slug = fx[:file].sub(/\.json\z/, '')
-      define_method("test_webhook_parse_tolerates_#{slug}") do
-        unless defined?(Jamm::Webhook) && Jamm::Webhook.respond_to?(:parse)
-          omit('webhook.parse absent in this version')
-        end
-
-        msg = Jamm::Webhook.parse(load_fixture(fx[:file]))
-        assert_equal(JammCompat::EXPECTED[:id], msg.content.id, fx[:event])
-        assert_equal(JammCompat::EXPECTED[:customer], msg.content.customer, fx[:event])
-      end
-    end
-  end
-end

data/compatibility/templates/Gemfile.tmpl

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/Gemfile.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=__VERSION__` from packages/sdk/ruby/compatibility.
-source 'https://rubygems.org'
-
-gem 'jamm', '__VERSION__'
-gem 'test-unit', '~> 3.0'

data/compatibility/templates/compat_test.rb.tmpl

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-# Generated from templates/compat_test.rb.tmpl -- do not edit by hand.
-# Regenerate with `make add VER=__VERSION__` from packages/sdk/ruby/compatibility.
-#
-# Installs the published jamm@__VERSION__ (pinned in the sibling Gemfile) and runs
-# the shared backward-compat suite against it. Requiring 'jamm' here -- under this
-# directory's bundle -- is what makes bundler resolve it to *this* pinned version.
-require 'jamm'
-
-require_relative '../shared/suite'
-
-class CompatTest < Test::Unit::TestCase
-  include JammCompat::Tests
-
-  SDK_VERSION = '__VERSION__'
-end