univapay-client-sdk 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67443648e1379446bcc69932c2cbf51c849dfbee244d15af946107a31003c4e7
-  data.tar.gz: 3e1b5d57cb796ed3b22c9e1711f7e0785a3e8c9ebf9ef3cd953055e39ea08847
+  metadata.gz: 1342c0449b6ee293db45dd5b397e5bc1ea581b98f57e4dd8b7f3790a05d191da
+  data.tar.gz: ca0a24c38e04b189c162e280f2ec33be5f808bdd3c15cfa11a375d490be422cc
 SHA512:
-  metadata.gz: 02f9e23da1f446c6efbfabea6ae225424ac388abba1e3ec6c46b1db81c5fa612ac3b2618e016dc25901fceac7bf277a0725443cf8783010b4a79655fe0d11611
-  data.tar.gz: bb65fb4d0322dce22c8145b81d7eee60ee3661ff3f8535e646a602398fc4a5d32d49f3b7c244c1ee2cf3ac08d7b17545c113bff6260f48141b222cbbfef1ca6c
+  metadata.gz: 1cc3a5d944d5c0e40e84b1ae3edc4ca6aee4d8123de4d325f23e1a99295aa093caa06a71057e1784313e8028a0b959d1c89a9ded07b895446fd09b5d78910111
+  data.tar.gz: 4446484ea04820ceee34cf5d50f758bf54a320c00ffc75cff2a90d4c1959209fc9d795d8aefd15de4d5f49e894aebfb07a521adb23273b05da10ef3d5680517f

data/README.md

@@ -36,16 +36,16 @@ We will assume that all requests are going to originate from a backend server th
 Install the gem from the command line:
 
 ```bash
-gem install univapay-client-sdk -v 1.0.0
+gem install univapay-client-sdk -v 1.0.1
 ```
 
 Or add the gem to your Gemfile and run `bundle`:
 
 ```ruby
-gem 'univapay-client-sdk', '1.0.0'
+gem 'univapay-client-sdk', '1.0.1'
 ```
 
-For additional gem details, see the [RubyGems page for the univapay-client-sdk gem](https://rubygems.org/gems/univapay-client-sdk/versions/1.0.0).
+For additional gem details, see the [RubyGems page for the univapay-client-sdk gem](https://rubygems.org/gems/univapay-client-sdk/versions/1.0.1).
 
 ## IRB Console Usage
 

data/lib/univapay_client_sdk/apis/base_api.rb

@@ -10,7 +10,7 @@ module UnivapayClientSdk
     attr_accessor :config, :http_call_back
 
     def self.user_agent
-      'Ruby-SDK/1.0.0 (OS: {os-info}, Engine: {engine}/{engine-version})'
+      'Ruby-SDK/1.0.1 (OS: {os-info}, Engine: {engine}/{engine-version})'
     end
 
     def self.user_agent_parameters

data/lib/univapay_client_sdk/extensions.rb

@@ -124,4 +124,97 @@ module UnivapayClientSdk
       get_subscription(store_id, id, polling: true)
     end
   end
+  # ── App token (JWT) claim decoding ────────────────────────────────────────
+  #
+  # A UnivaPay app token JWT carries the context it was issued for. A
+  # store-level token has both `merchant_id` and `store_id`; a merchant-level
+  # token has only `merchant_id`.
+  #
+  # Decoding only reads the payload segment -- it does NOT verify the
+  # signature, which is deliberate. The value is the caller's own credential,
+  # already trusted by virtue of being configured on the client; nothing here
+  # is an authorization decision. Never use these values to authenticate a
+  # third party's token.
+  module AppJwt
+    # Matches the canonical 8-4-4-4-12 hexadecimal UUID form.
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.freeze
+
+    # Decodes the payload segment of a JWT without verifying its signature.
+    #
+    # @param jwt_token [String, nil] The JWT to decode.
+    # @return [Hash, nil] The decoded claims, or nil unless the token is a
+    #   well-formed three-segment JWT whose payload segment is base64url-encoded
+    #   JSON describing an object.
+    def self.decode_payload(jwt_token)
+      return nil if jwt_token.nil? || !jwt_token.is_a?(String) || jwt_token.empty?
+
+      segments = jwt_token.split('.', -1)
+      return nil unless segments.length == 3
+
+      begin
+        # unpack1('m0') is strict base64 and needs no `base64` gem, which stopped
+        # being a default gem in Ruby 3.4. It requires correct padding, so
+        # translate base64url to base64 and pad first.
+        base64 = segments[1].tr('-_', '+/')
+        base64 += '=' * ((4 - (base64.length % 4)) % 4)
+        payload = JSON.parse(base64.unpack1('m0'))
+      rescue ArgumentError, JSON::ParserError
+        return nil
+      end
+      payload.is_a?(Hash) ? payload : nil
+    end
+
+    # Reads a claim from a JWT payload and returns it only if it is a UUID.
+    #
+    # Anything else -- claim absent, nil, not a string, or a string that is not
+    # a canonical UUID -- yields nil, so a caller never has to distinguish "not
+    # set" from "could not decode".
+    #
+    # @param jwt_token [String, nil] The JWT to decode.
+    # @param claim [String] Name of the claim to read.
+    # @return [String, nil] The claim value as a UUID string, or nil.
+    def self.read_uuid_claim(jwt_token, claim)
+      payload = decode_payload(jwt_token)
+      return nil if payload.nil?
+
+      value = payload[claim]
+      value.is_a?(String) && UUID_PATTERN.match?(value) ? value : nil
+    end
+  end
+
+  # Reopened onto the generated client class to expose the app token's context.
+  class Client
+    # The merchant this client's app token was issued for, decoded from the
+    # configured JWT.
+    #
+    # Both merchant-level and store-level app tokens carry a merchant, so this
+    # is set for either kind of token.
+    #
+    # @return [String, nil] The merchant id as a UUID string, or nil if no JWT
+    #   is configured or its `merchant_id` claim is absent or not a UUID.
+    def get_current_merchant_id
+      AppJwt.read_uuid_claim(jwt_token_or_nil, 'merchant_id')
+    end
+
+    # The store this client's app token was issued for, decoded from the
+    # configured JWT.
+    #
+    # Only store-level app tokens are scoped to a store. A merchant-level token
+    # carries no `store_id` claim, so this returns nil for one -- use `stores`
+    # to list the merchant's stores instead.
+    #
+    # @return [String, nil] The store id as a UUID string, or nil if no JWT is
+    #   configured or its `store_id` claim is absent or not a UUID.
+    def get_current_store_id
+      AppJwt.read_uuid_claim(jwt_token_or_nil, 'store_id')
+    end
+
+    private
+
+    # The configured JWT, or nil when no credentials are set.
+    def jwt_token_or_nil
+      config.bearer_auth_credentials&.jwt_token
+    end
+  end
+
 end

data/test/test_app_jwt.rb

@@ -0,0 +1,117 @@
+# Custom test (not auto-generated): pins the App Token claim-decoding contract
+# behind get_current_merchant_id / get_current_store_id.
+#
+# This contract is implemented seven times -- once per SDK -- and has already
+# drifted twice: the Python SDK accepted non-canonical UUIDs that the others
+# rejected, and the TypeScript SDK rejected a payload segment carrying '='
+# padding that the others accepted. Neither was caught by a test, because none
+# existed.
+#
+# So the cases below are deliberately a *shared table*: keep them identical in
+# all seven SDKs. The failure being guarded against is the languages disagreeing
+# with each other, which no single-language suite can see.
+#
+# Everything here is synthetic and offline -- no network, no environment, no real
+# credential. It must pass in CI, where no token is configured.
+
+require 'json'
+require 'minitest/autorun'
+require 'univapay_client_sdk'
+
+class AppJwtTest < Minitest::Test
+  include UnivapayClientSdk
+
+  MERCHANT_ID = '11ec8e24-0ecf-2c5a-923c-331b915dc311'.freeze
+  STORE_ID = '11ec8e24-b133-6c68-b54d-971717202e9b'.freeze
+
+  # pack('m0') is strict base64 and needs no `base64` gem, which stopped being a
+  # default gem in Ruby 3.4 -- the same reason the SDK itself avoids it.
+  def base64url(bytes, padded: false)
+    encoded = [bytes].pack('m0').tr('+/', '-_')
+    padded ? encoded : encoded.delete('=')
+  end
+
+  # Builds a JWT carrying `claims`. Header and signature are inert.
+  def jwt(claims, padded: false)
+    header = base64url('{"alg":"HS256","typ":"JWT"}')
+    "#{header}.#{base64url(JSON.generate(claims), padded: padded)}.c2ln"
+  end
+
+  # Builds a JWT whose payload segment is `payload`, base64url-encoded.
+  def raw_jwt(payload)
+    "aGRy.#{base64url(payload)}.c2ln"
+  end
+
+  def client_with(jwt_token)
+    Client.new(
+      bearer_auth_credentials: BearerAuthCredentials.new(
+        secret_key: 'not-a-real-secret', jwt_token: jwt_token
+      )
+    )
+  end
+
+  def test_reads_both_ids_from_store_level_token
+    client = client_with(jwt({ 'merchant_id' => MERCHANT_ID, 'store_id' => STORE_ID }))
+
+    assert_equal MERCHANT_ID, client.get_current_merchant_id
+    assert_equal STORE_ID, client.get_current_store_id
+  end
+
+  def test_reads_merchant_from_merchant_level_token_and_reports_no_store
+    # A merchant-level token carries no store_id claim at all. nil here is the
+    # correct answer, not a decoding failure.
+    client = client_with(jwt({ 'merchant_id' => MERCHANT_ID }))
+
+    assert_equal MERCHANT_ID, client.get_current_merchant_id
+    assert_nil client.get_current_store_id
+  end
+
+  def test_accepts_payload_segment_that_carries_padding
+    # The TypeScript SDK once rejected exactly this, making it the only one of
+    # the seven to return nil for a padded -- but still valid -- token.
+    client = client_with(jwt({ 'merchant_id' => MERCHANT_ID, 'store_id' => STORE_ID }, padded: true))
+
+    assert_equal MERCHANT_ID, client.get_current_merchant_id
+    assert_equal STORE_ID, client.get_current_store_id
+  end
+
+  def test_returns_nil_never_raises_for_unusable_input
+    cases = [
+      ['a claim that is JSON null', jwt({ 'store_id' => nil })],
+      ['a claim that is not a string', jwt({ 'store_id' => 42 })],
+      ['an undashed 32-character UUID', jwt({ 'store_id' => STORE_ID.delete('-') })],
+      ['a braced UUID', jwt({ 'store_id' => "{#{STORE_ID}}" })],
+      ['a urn:uuid: prefixed UUID', jwt({ 'store_id' => "urn:uuid:#{STORE_ID}" })],
+      ['short hex groups (1-1-1-1-1)', jwt({ 'store_id' => '1-1-1-1-1' })],
+      ['a UUID with a trailing newline', jwt({ 'store_id' => "#{STORE_ID}\n" })],
+      ['a UUID padded with spaces', jwt({ 'store_id' => " #{STORE_ID} " })],
+      ['a two-segment token', 'aGRy.c2ln'],
+      ['a payload that is not base64url', 'aGRy.!!!!.c2ln'],
+      ['a payload that is a JSON array', raw_jwt('[1,2]')],
+      ['a payload that is not JSON', raw_jwt('definitely not json')],
+      ['an empty string', ''],
+      # The Authorization header value is {secret}.{jwt} -- four segments once
+      # split. Pasting that whole value into the jwt_token field is the mistake
+      # the guide warns about, and it must degrade to nil, not to a wrong id.
+      ['the combined {secret}.{jwt} header value', "c2VjcmV0.#{jwt({ 'store_id' => STORE_ID })}"]
+    ]
+
+    failures = cases.filter_map do |label, token|
+      begin
+        store_id = client_with(token).get_current_store_id
+        "#{label} -> expected nil but got #{store_id.inspect}" unless store_id.nil?
+      rescue StandardError => e
+        "#{label} -> raised #{e.class}: #{e.message}"
+      end
+    end
+
+    assert_empty failures, "cases that did not degrade to nil:\n  #{failures.join("\n  ")}"
+  end
+
+  def test_returns_nil_when_no_credentials_configured
+    client = Client.new
+
+    assert_nil client.get_current_merchant_id
+    assert_nil client.get_current_store_id
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: univapay-client-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Univapay Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: apimatic_core_interfaces
@@ -340,6 +340,7 @@ files:
 - test/framework_integrations/webhooks/test/test_rails_charge_app.rb
 - test/framework_integrations/webhooks/test/test_sinatra_charge_app.rb
 - test/http_response_catcher.rb
+- test/test_app_jwt.rb
 homepage: https://univapay.com
 licenses:
 - MIT