jamm 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dc69a9799a5215efa21041879db8ee9d8b67678dc6ac20dc92046c165eec6fd
-  data.tar.gz: 33bd5a72e96fdc0212e956762e5bb7983604a5d1a1e9792d577267a61a2d96bd
+  metadata.gz: 17f04171e0380f881d022d968eafaecfab7de2ca6e0a91ed56b217a4434afcab
+  data.tar.gz: 2f98a4766f79146afc5a839a26b2f69674ac87330065f663d9c90441a52b5f74
 SHA512:
-  metadata.gz: 82fd64ead34ca1e458d831d21874ccb6bd53774e27170944a2c8d4d1532dcad9db4e589ffe55ce4a24b60bbd658f8816aebcc674afc6f5d096ba931ec1ae2806
-  data.tar.gz: f8d88d108bcd9822c56a05133248bf759b100f31ef3af3bc5b7f5ed14ea4c7ba5d111ca96a482fec038e5de09ac10d769d7d559ab57ac53dcb64dbbc9ce21785
+  metadata.gz: 1182b1fc82f6d8c009e9f98542baf35e2b4542ff81f8b49ba4de35319662a8a2bcec5e47f35b2f45041a491f4d9c7697997259263426960d11493cefa0eef547
+  data.tar.gz: a17d3a2f3a352b39a8c2021593dc24e4d960afd460bc2ecdea038186b078e9df92d8b6e6b0e9965995cf50408c1327eef01dbd3ffd39909aa222636e8155b337

data/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.4.0] - 2026-07-01
+
+### Added
+
+- Send the `X-SDK-Version` request header (`ruby:<version>`) so the backend can track SDK version usage per merchant
+
 ## [2.2.0] - 2026-05-20
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jamm (2.2.0)
+    jamm (2.4.0)
       base64 (~> 0.2)
       rest-client (~> 2.0)
       typhoeus (~> 1.0, >= 1.0.1)
@@ -15,7 +15,7 @@ GEM
     base64 (0.3.0)
     bigdecimal (3.1.7)
     coderay (1.1.3)
-    concurrent-ruby (1.3.4)
+    concurrent-ruby (1.3.7)
     crack (1.0.0)
       bigdecimal
       rexml
@@ -24,7 +24,9 @@ GEM
       ffi (>= 1.15.0)
     faker (3.5.1)
       i18n (>= 1.8.11, < 2)
-    ffi (1.17.0)
+    ffi (1.17.0-aarch64-linux-gnu)
+    ffi (1.17.0-arm64-darwin)
+    ffi (1.17.0-x86_64-linux-gnu)
     gimei (1.5.0)
     hashdiff (1.1.0)
     http-accept (1.7.0)

data/compatibility/.gitignore

@@ -0,0 +1,11 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,63 @@
+.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

@@ -0,0 +1,119 @@
+# 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

@@ -0,0 +1,146 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

data/lib/jamm/api/models/v1_error_type.rb

@@ -37,6 +37,8 @@ module Api
     PAYMENT_CHARGE_INSUFFICIENT_FUNDS = "ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS".freeze
     PAYMENT_CUSTOMER_NOT_FOUND = "ERROR_TYPE_PAYMENT_CUSTOMER_NOT_FOUND".freeze
     PAYMENT_CUSTOMER_INACTIVE = "ERROR_TYPE_PAYMENT_CUSTOMER_INACTIVE".freeze
+    PAYMENT_SERVICE_DISABLED = "ERROR_TYPE_PAYMENT_SERVICE_DISABLED".freeze
+    PAYMENT_BANK_UNAVAILABLE = "ERROR_TYPE_PAYMENT_BANK_UNAVAILABLE".freeze
     CSV_VALIDATION_FAILED = "ERROR_TYPE_CSV_VALIDATION_FAILED".freeze
     CSV_TOTP_REQUIRED = "ERROR_TYPE_CSV_TOTP_REQUIRED".freeze
     CSV_TOTP_INVALID = "ERROR_TYPE_CSV_TOTP_INVALID".freeze
@@ -54,7 +56,7 @@ module Api
     TOTP_DISABLE_FAILED = "ERROR_TYPE_TOTP_DISABLE_FAILED".freeze
 
     def self.all_vars
-      @all_vars ||= [UNSPECIFIED, AUTH_FAILED, AUTH_REJECTED, ACCOUNT_CREATION_FAILED, ACCOUNT_MODIFICATION_FAILED, ACCOUNT_DELETION_FAILED, ACCOUNT_BANK_REGISTRATION_FAILED, KYC_REJECTED, NOTIFICATION_WEBHOOK_FAILED, NOTIFICATION_EMAIL_FAILED, NOTIFICATION_SMS_FAILED, PAYMENT_GATEWAY_UNAVAILABLE, PAYMENT_GATEWAY_FAILED, PAYMENT_VALIDATION_FAILED, PAYMENT_CHARGE_FAILED, PAYMENT_CHARGE_REJECTED, PAYMENT_CHARGE_OVER_LIMIT, PAYMENT_CHARGE_SUBSCRIPTION_EXPIRED, PAYMENT_LINK_EXPIRED, PAYMENT_CHARGE_INSUFFICIENT_FUNDS, PAYMENT_CUSTOMER_NOT_FOUND, PAYMENT_CUSTOMER_INACTIVE, CSV_VALIDATION_FAILED, CSV_TOTP_REQUIRED, CSV_TOTP_INVALID, CSV_TOTP_EXPIRED, CSV_TOTP_LOCKED, CSV_BATCH_TOO_LARGE, CSV_CUSTOMER_NOT_FOUND, CSV_PROCESSING_FAILED, CSV_CHALLENGE_NOT_FOUND, CSV_DUPLICATE_USER, TOTP_SETUP_FAILED, TOTP_ALREADY_ENABLED, TOTP_NOT_ENABLED, TOTP_SETUP_INVALID, TOTP_DISABLE_FAILED].freeze
+      @all_vars ||= [UNSPECIFIED, AUTH_FAILED, AUTH_REJECTED, ACCOUNT_CREATION_FAILED, ACCOUNT_MODIFICATION_FAILED, ACCOUNT_DELETION_FAILED, ACCOUNT_BANK_REGISTRATION_FAILED, KYC_REJECTED, NOTIFICATION_WEBHOOK_FAILED, NOTIFICATION_EMAIL_FAILED, NOTIFICATION_SMS_FAILED, PAYMENT_GATEWAY_UNAVAILABLE, PAYMENT_GATEWAY_FAILED, PAYMENT_VALIDATION_FAILED, PAYMENT_CHARGE_FAILED, PAYMENT_CHARGE_REJECTED, PAYMENT_CHARGE_OVER_LIMIT, PAYMENT_CHARGE_SUBSCRIPTION_EXPIRED, PAYMENT_LINK_EXPIRED, PAYMENT_CHARGE_INSUFFICIENT_FUNDS, PAYMENT_CUSTOMER_NOT_FOUND, PAYMENT_CUSTOMER_INACTIVE, PAYMENT_SERVICE_DISABLED, PAYMENT_BANK_UNAVAILABLE, CSV_VALIDATION_FAILED, CSV_TOTP_REQUIRED, CSV_TOTP_INVALID, CSV_TOTP_EXPIRED, CSV_TOTP_LOCKED, CSV_BATCH_TOO_LARGE, CSV_CUSTOMER_NOT_FOUND, CSV_PROCESSING_FAILED, CSV_CHALLENGE_NOT_FOUND, CSV_DUPLICATE_USER, TOTP_SETUP_FAILED, TOTP_ALREADY_ENABLED, TOTP_NOT_ENABLED, TOTP_SETUP_INVALID, TOTP_DISABLE_FAILED].freeze
     end
 
     # Builds the enum from string

data/lib/jamm/api/models/v1_initial_charge.rb

@@ -22,7 +22,7 @@ module Api
     # Description is an arbitrary string for merchant to track the charge. This information is displayed on Merchant Dashboard.  決済の説明。ショップが決済を追跡するための任意の文字列です。  @gotags: validate:\"required,max=1024\"
     attr_accessor :description
 
-    # Arbitrary key-value additional information about the charge. You can see this information in our merchant dashboard.  ## Testing with triggerError  Set the key \"triggerError\" to a valid ERROR_TYPE_* enum name (e.g. \"ERROR_TYPE_PAYMENT_CHARGE_FAILED\") to simulate a payment failure. Behavior differs by flow:  Off-session (Withdraw, WithdrawAsync, OffSessionPayment, OffSessionPaymentAsync):   Reads triggerError from this field (charge.metadata).   Creates a failed transaction record and sends a failure webhook.   Returns transport-level 400 for ERROR_TYPE_PAYMENT_VALIDATION_FAILED,   500 for all other ERROR_TYPE_* values.  On-session (InitiatePayment / ApprovePayment — consumer-facing core service):   Reads triggerError from the payment's stored metadata (charge or merchant-customer).   Initiate stage: only ERROR_TYPE_PAYMENT_VALIDATION_FAILED and     ERROR_TYPE_PAYMENT_LINK_EXPIRED are honored; other types are ignored.     No failed transaction or webhook is created. Returns 200 OK with     an embedded InitiatePaymentError payload.   Approve stage: all ERROR_TYPE_* values are honored.     Creates workflow-specific failure records (cancelled contract and/or     failed transaction depending on the workflow type). Returns 200 OK with     an embedded ApprovePaymentError payload.  Note: CreateContractWithoutCharge has no charge, so this field does not apply. On-session triggerError for that flow is read from merchant-customer metadata instead.  ## Error types by payment stage  Initiate (payment session setup, workflow creation):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired  Approve (pre-charge validation + BankPay charge execution):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request (e.g. deleted/inactive customer)   - ERROR_TYPE_PAYMENT_CHARGE_REJECTED    — KYC not approved   - ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMIT  — charge exceeds bank quota   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired   - ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLE — BankPay/bank under maintenance   - ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS — insufficient funds in customer's account   - ERROR_TYPE_PAYMENT_GATEWAY_FAILED     — BankPay rejected the charge   - ERROR_TYPE_PAYMENT_CHARGE_FAILED      — generic charge failure (internal, not found, etc.)  Chargeに関する任意のキーと値の追加情報。 加盟店ダッシュボードで確認できます。  テスト環境では、\"triggerError\" キーに ERROR_TYPE_* の列挙名を設定すると 決済エラーをシミュレートできます。動作はフローによって異なります。 詳細は上記の英語コメントを参照してください。
+    # Arbitrary key-value additional information about the charge. You can see this information in our merchant dashboard.  ## Testing with triggerError  Set the key \"triggerError\" to a valid ERROR_TYPE_* enum name (e.g. \"ERROR_TYPE_PAYMENT_CHARGE_FAILED\") to simulate a payment failure. Behavior differs by flow:  Off-session (Withdraw, WithdrawAsync, OffSessionPayment, OffSessionPaymentAsync):   Reads triggerError from this field (charge.metadata).   Creates a failed transaction record and sends a failure webhook.   Returns transport-level 400 for ERROR_TYPE_PAYMENT_VALIDATION_FAILED,   500 for all other ERROR_TYPE_* values.  On-session (InitiatePayment / ApprovePayment — consumer-facing core service):   Reads triggerError from the payment's stored metadata (charge or merchant-customer).   Initiate stage: only ERROR_TYPE_PAYMENT_VALIDATION_FAILED and     ERROR_TYPE_PAYMENT_LINK_EXPIRED are honored; other types are ignored.     No failed transaction or webhook is created. Returns 200 OK with     an embedded InitiatePaymentError payload.   Approve stage: all ERROR_TYPE_* values are honored.     Creates workflow-specific failure records (cancelled contract and/or     failed transaction depending on the workflow type). For charge-bearing     workflows it also sends a charge.fail webhook (api_source ON_SESSION),     mirroring off-session triggerError and real on-session failures.     Returns 200 OK with an embedded ApprovePaymentError payload.  Note: CreateContractWithoutCharge has no charge, so this field does not apply. On-session triggerError for that flow is read from merchant-customer metadata instead.  ## Error types by payment stage  Initiate (payment session setup, workflow creation):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired  Approve (pre-charge validation + BankPay charge execution):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request (e.g. deleted/inactive customer)   - ERROR_TYPE_PAYMENT_CHARGE_REJECTED    — KYC not approved   - ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMIT  — charge exceeds bank quota   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired   - ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLE — BankPay/bank under maintenance   - ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS — insufficient funds in customer's account   - ERROR_TYPE_PAYMENT_GATEWAY_FAILED     — BankPay rejected the charge   - ERROR_TYPE_PAYMENT_CHARGE_FAILED      — generic charge failure (internal, not found, etc.)  Chargeに関する任意のキーと値の追加情報。 加盟店ダッシュボードで確認できます。  テスト環境では、\"triggerError\" キーに ERROR_TYPE_* の列挙名を設定すると 決済エラーをシミュレートできます。動作はフローによって異なります。 詳細は上記の英語コメントを参照してください。
     attr_accessor :metadata
 
     # Fee charged by the platform (in JPY). Must be >= the Jamm fee for the merchant. Only meaningful when the caller is a platform. Ignored for direct merchant calls.  プラットフォームが徴収する手数料（日本円）。加盟店のJamm手数料以上である必要があります。

data/lib/jamm/client.rb

@@ -9,6 +9,7 @@ module Jamm
       base.config.host = Jamm.openapi.config.host
       base.config.scheme = Jamm.openapi.config.scheme
       base.default_headers['Authorization'] = "Bearer #{Jamm::OAuth.token}"
+      base.default_headers['X-SDK-Version'] = "ruby:#{Jamm::VERSION}"
 
       # Platform feature, optionally set merchant id to call Jamm API
       # on behalf of the merchant.

data/lib/jamm/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jamm
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Jamm
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -72,6 +72,32 @@ 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