jamm 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe888992acfb9739e5206ab7aaa3428f3e246998e633ff60e09999c2d96f3992
-  data.tar.gz: 6ee9932e4775b93a8b18e9dba2173871d6c36b0e727563111c8462801db481e3
+  metadata.gz: f15af21a2f10a3f3ea2c5636349ab7449d90997795bb8e9a729d063a02c70040
+  data.tar.gz: 48f9b4782863261fb11c8ce3e37f5f0819c8b87d24136c595df7396a0cbfd3b5
 SHA512:
-  metadata.gz: c33699a5edbb8cd8f52c5848bc5534b735f9ebca0990b45ceb2105408a2e5fbad7aca6205a0f788c5b6213e954d9a9c56e7d7f71f8f2cb47f491f7786afe658d
-  data.tar.gz: 73722cb39c3acbbd828c8011e4303f0ff1a8936b1dd390f34edbef5fe9dc26cf3375d6f025a8b20c8abd3e2a37fe80e3fbdc97b195dbbd899fcde93a099c3260
+  metadata.gz: 18be3aac7a0654593d068e7e8f7c889e02d6df8bf66bd6c00d024fd15aeff33f4611055a902f223f4fdfcb7e6dd518c0a3c27659bf79a9f030bcb39846ed9c54
+  data.tar.gz: 214589958f50dda8837dbc9d27017597fb9d88f10ee02923eee15ff278b6b1d5e7f809412dd0c5a6b475a936de575fff6f69c19949a4dec8fa06efcc41baccd2

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jamm (2.5.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/lib/jamm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jamm
-  VERSION = '2.5.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)
-
-      case json[:event_type]
-      when Jamm::OpenAPI::EventType::CHARGE_CREATED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      # 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)
+
+      out = build(Jamm::OpenAPI::MerchantWebhookMessage, json)
+
+      # 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::CHARGE_UPDATED
-        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_SUCCEEDED
-        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::REFUND_FAILED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+      raise 'Unknown event type'
+    end
 
-      when Jamm::OpenAPI::EventType::CHARGE_SUCCESS
-        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?
+
+      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
 
-      when Jamm::OpenAPI::EventType::CHARGE_FAIL
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+      klass.new(filtered)
+    end
 
-      when Jamm::OpenAPI::EventType::CONTRACT_ACTIVATED
-        out.content = Jamm::OpenAPI::ContractMessage.new(json[:content])
-        return out
+    # 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
 
-      raise 'Unknown event type'
+    # 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jamm
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Jamm
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64