tango-api-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: becdf70f2093e91de7a7e7e1fbfd2c5dadbed25dffb8af5e00d330f4bdeebc3c
+  data.tar.gz: a0175048faf72fef7d89acf67e1fdf2d7649bff9a985d57ca88520e3e3f87c41
+SHA512:
+  metadata.gz: 8f09484e472d1ec10e64019d00def0eed0821a4786b7fe11305ee7bcb1fcf5cae8d5a0f0521812176c1ff0a65b43cef25bec7afd6bec87a85d3b1fc4fd6a1f88
+  data.tar.gz: a2ed02aeec6a39e94a7be633e194a901c79d09eca09f253a3372b62a2b6792dc3513975bde325cf0fa189e667e7e88840df22edfab95c154e58ed48825b191ba

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-11-07
+- Initial release
+- Basic and OAuth2 auth strategies
+- Catalogs#get, Orders#create, Accounts#get, Funds (register/unregister/add), Customers#create, Accounts#create
+- Faraday-based client with retries/timeouts
+- Structured error mapping
+- README and RSpec scaffolding

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,181 @@
+# tango-api-client
+
+Ruby client for Tango (BHN) API with dual auth (Basic/OAuth2), flexible parameterization, retries/timeouts, and structured errors.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add tango-api-client
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install tango-api-client
+```
+
+## Usage
+
+```ruby
+require "tango/api/client"
+
+Tango::Api.configure do |c|
+  c.base_url = ENV["TANGO_URL"]
+  c.timeout = 45
+  c.retries = { max: 2, base: 0.5, max_delay: 5 }
+  # Basic auth
+  c.auth = Tango::Api::Auth::Basic.new(platform: ENV["TANGO_PLATFORM"], key: ENV["TANGO_KEY"])
+  # or OAuth2
+  # c.auth = Tango::Api::Auth::OAuth2.new(
+  #   token_url: ENV["TANGO_TOKEN_URL"],
+  #   client_id: ENV["TANGO_CLIENT_ID"],
+  #   client_secret: ENV["TANGO_CLIENT_SECRET"],
+  #   scope: ENV["TANGO_SCOPE"]
+  # )
+end
+
+client = Tango::Api::Client.new
+
+# Alternatively, pass a base URL string directly
+# (convenient for scripts or isolated clients)
+client = Tango::Api::Client.new("https://integration-api.tangocard.com/raas/v2")
+
+# Or pass a configuration hash for explicit per-client settings
+client = Tango::Api::Client.new(
+  base_url: "https://integration-api.tangocard.com/raas/v2",
+  timeout: 60,
+  retries: { max: 3, base: 0.5, max_delay: 8 },
+  default_headers: { "Accept-Language" => "en-US" }
+)
+
+# Catalogs
+client.catalogs.get(country: 'US', status: 'active', verbose: true, rewardType: ['gift card','payment card'], categoryIds: 'uuid1,uuid2', currency: 'USD')
+
+# Orders
+client.orders.create(accountIdentifier: 'acc', amount: 1000, customerIdentifier: 'cust', utid: 'UT...', recipient: { email: 'a@b.com', firstName: 'A' }, sendEmail: true)
+
+# Accounts
+client.accounts.get('acc-identifier')
+
+# Create Account for a Customer
+client.accounts.create('customer-identifier', { accountIdentifier: 'new-acc', currency: 'USD' })
+
+# Customers
+client.customers.create({ customerIdentifier: 'cust', name: 'ACME Inc.' })
+# List and filter customers
+client.customers.list(displayName: 'ACME', status: 'active')
+# Fetch a specific customer
+client.customers.get('cust')
+
+# Funds
+client.funds.register_card({ accountIdentifier: 'acc', card: { number: '4111...', expiryMonth: '12', expiryYear: '2030' } })
+client.funds.add_funds({ accountIdentifier: 'acc', amount: 5000 })
+client.funds.unregister_card({ accountIdentifier: 'acc' })
+
+# Error handling
+begin
+  client.accounts.get('missing')
+rescue Tango::Api::Errors::HttpError => e
+  puts "Error: #{e.class} status=#{e.status} request_id=#{e.request_id} message=#{e.message}"
+end
+```
+
+### Notes
+- Retries apply to idempotent HTTP methods (GET/HEAD/OPTIONS) with backoff and jitter.
+- Ruby >= 3.0 is required.
+- `base_url` is required (e.g., `https://api.tangocard.com/raas/v2`).
+- Initialization options:
+  - Global config (recommended for Rails/apps): use `Tango::Api.configure { ... }` then `Tango::Api::Client.new`.
+  - Per-client overrides: pass a config hash to `Client.new(...)`.
+  - Convenience: passing a base URL string to `Client.new("https://...")` is supported for quick scripts.
+
+### Examples
+
+```ruby
+# Catalogs convenience filters
+client.catalogs.get_by_brand_key('AMAZON', verbose: true)
+client.catalogs.get_by_brand_name('Amazon', country: 'US')
+client.catalogs.get_by_utid('UT123456')
+client.catalogs.get_by_reward_name('Gift Card')
+
+# Choice Products
+client.choice_products.get(rewardName: 'Choice', currencyCode: 'USD', countries: ['US'])
+client.choice_products.get_for_utid('UT-CHOICE-123')
+client.choice_products.catalog('UT-CHOICE-123', verbose: true, country: 'US')
+
+# Orders with Idempotency-Key for safe retries
+require 'securerandom'
+idempotency = SecureRandom.uuid
+client.orders.create(
+  { accountIdentifier: 'acc', amount: 1000, customerIdentifier: 'cust', utid: 'UT123', recipient: { email: 'a@b.com' } },
+  idempotency_key: idempotency
+)
+
+# Resend with Idempotency-Key (prevents duplicate resends)
+client.orders.resend('ORDER-123', idempotency_key: idempotency)
+```
+
+### Resources overview
+
+| Resource  | Class                             | Methods (args)                                                                        | HTTP / Path                                        |
+|-----------|-----------------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------|
+| Catalogs  | `Tango::Api::Resources::Catalogs` | `get(params = {})`                                                                     | GET `/catalogs`                                    |
+| Orders    | `Tango::Api::Resources::Orders`   | `create(body)`, `get(order_id)`, `list(params = {})`, `resend(order_id)`               | POST `/orders`; GET `/orders/{id}`; GET `/orders`; POST `/orders/{id}/resend` |
+| Accounts  | `Tango::Api::Resources::Accounts` | `get(account_identifier)`, `list_for_customer(customer_identifier, params)`, `create(customer_identifier, body)`, `update_under_customer(customer_identifier, account_identifier, body)`, low balance alerts: `list_low_balance_alerts`, `set_low_balance_alert`, `get_low_balance_alert`, `update_low_balance_alert`, `delete_low_balance_alert` | GET `/accounts/{accountIdentifier}`; GET/POST/PATCH/DELETE under `/customers/{customerIdentifier}/accounts/...` |
+| Customers | `Tango::Api::Resources::Customers`| `list(params = {})`, `get(customer_identifier)`, `create(body)`, `accounts(customer_identifier, params)` | GET `/customers`; GET `/customers/{customerIdentifier}`; POST `/customers`; GET `/customers/{customerIdentifier}/accounts` |
+| Funds     | `Tango::Api::Resources::Funds`    | `register_card(body)`, `unregister_card(body)`, `add_funds(body)`                      | POST `/funds/registerCreditCard`; `/funds/unregisterCreditCard`; `/funds/add` |
+| Status    | `Tango::Api::Resources::Status`   | `get`                                                                                  | GET `/status`                                      |
+| Exchange Rates | `Tango::Api::Resources::ExchangeRates` | `get(params = {})`, `get_for_utid(utid, params = {})`                            | GET `/exchangeRates`; GET `/exchangeRates/{utid}`  |
+| Choice Products | `Tango::Api::Resources::ChoiceProducts` | `get(params = {})`, `get_for_utid(utid)`, `catalog(choice_product_utid, params = {})` | GET `/choiceProducts`; GET `/choiceProducts/{utid}`; GET `/choiceProducts/{utid}/catalog` |
+
+### Smoke test
+
+Run a basic end-to-end check against your Tango environment.
+
+Required:
+
+```bash
+export TANGO_URL=https://integration-api.tangocard.com/raas/v2
+export TANGO_PLATFORM=QAPlatform2
+export TANGO_KEY=YOUR_BASIC_KEY
+```
+
+Run:
+
+```bash
+bin/smoke
+```
+
+Optional flags:
+
+- SMOKE_RUN_STATUS=true: call `/status` (may be 404 on RAAS v2)
+- SMOKE_RUN_EXCHANGE_RATES=true: call `/exchangerates`
+- TANGO_RUN_MUTATIONS=true: enable POST flows (create/update/delete)
+
+Optional data variables (used when present):
+
+- TANGO_ACCOUNT_IDENTIFIER, TANGO_CUSTOMER_IDENTIFIER
+- TANGO_ORDER_IDENTIFIER, TANGO_ORDER_AMOUNT (default 100)
+- TANGO_UTID or TANGO_CHOICE_PRODUCT_UTID for order/choice product flows
+- TANGO_RECIPIENT_EMAIL
+- Low balance alerts:
+  - TANGO_LOW_BALANCE_ALERT_BODY (JSON) or individual fields:
+  - TANGO_LOW_BALANCE_ALERT_DISPLAY_NAME, TANGO_LOW_BALANCE_ALERT_THRESHOLD, TANGO_LOW_BALANCE_ALERT_EMAIL
+
+At the end, the script prints a summary of passed/failed checks with statuses and messages.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Engagedly-Inc/tango-api-client.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/tango/api/auth/basic.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Tango
+  module Api
+    module Auth
+      # Basic authentication helper for Tango API.
+      class Basic
+        def initialize(platform:, key:)
+          @platform = platform
+          @key = key
+        end
+
+        def apply(headers)
+          token = ::Base64.strict_encode64("#{@platform}:#{@key}")
+          headers["Authorization"] = "Basic #{token}"
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/auth/oauth2.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "logger"
+
+module Tango
+  module Api
+    module Auth
+      # OAuth2 client credentials flow helper that injects Bearer tokens.
+      class OAuth2
+        Token = Struct.new(:access_token, :expires_at)
+
+        def initialize(token_url:, client_id:, client_secret:, scope: nil, logger: nil)
+          @token_url = token_url
+          @client_id = client_id
+          @client_secret = client_secret
+          @scope = scope
+          @logger = logger || (defined?(Rails) ? Rails.logger : Logger.new($stdout))
+          @mutex = Mutex.new
+          @token = nil
+        end
+
+        def apply(headers)
+          token = fetch_token
+          headers["Authorization"] = "Bearer #{token}"
+        end
+
+        private
+
+        def fetch_token
+          @mutex.synchronize do
+            return @token.access_token if @token && Time.now < (@token.expires_at - 60)
+
+            uri = URI(@token_url)
+            req = Net::HTTP::Post.new(uri)
+            req["Content-Type"] = "application/x-www-form-urlencoded"
+            body = {
+              grant_type: "client_credentials",
+              client_id: @client_id,
+              client_secret: @client_secret
+            }
+            body[:scope] = @scope if @scope
+            req.body = URI.encode_www_form(body)
+
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = uri.scheme == "https"
+            http.read_timeout = 10
+            http.open_timeout = 5
+            res = http.request(req)
+
+            unless res.is_a?(Net::HTTPSuccess)
+              @logger.error "OAuth2 token request failed: #{res.code} #{res.body}"
+              raise StandardError, "OAuth2 token request failed with #{res.code}"
+            end
+
+            data = JSON.parse(res.body)
+            expires_in = (data["expires_in"] || 3600).to_i
+            @token = Token.new(data["access_token"], Time.now + expires_in)
+            @token.access_token
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/client/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    class Client
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/tango/api/client.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/follow_redirects"
+require "faraday/retry"
+require "json"
+
+require_relative "client/version"
+require_relative "../api"
+require_relative "errors"
+require_relative "auth/basic"
+require_relative "auth/oauth2"
+require_relative "resources/base"
+require_relative "resources/catalogs"
+require_relative "resources/accounts"
+require_relative "resources/orders"
+require_relative "resources/funds"
+require_relative "resources/customers"
+require_relative "resources/status"
+require_relative "resources/exchange_rates"
+require_relative "resources/choice_products"
+
+module Tango
+  module Api
+    # Public client to interact with Tango API resources via Faraday.
+    class Client
+      def initialize(config = Tango::Api.configuration)
+        @config =
+          case config
+          when String
+            cfg = Tango::Api.configuration.dup
+            cfg.base_url = config
+            cfg
+          when Hash
+            cfg = Tango::Api.configuration.dup
+            config.each do |key, value|
+              writer = "#{key}="
+              cfg.public_send(writer, value) if cfg.respond_to?(writer)
+            end
+            cfg
+          else
+            config
+          end
+        raise ArgumentError, "Tango::Api.configuration.base_url is required" if @config.base_url.to_s.strip.empty?
+
+        @conn = build_connection
+      end
+
+      def catalogs
+        Resources::Catalogs.new(@conn)
+      end
+
+      def accounts
+        Resources::Accounts.new(@conn)
+      end
+
+      def orders
+        Resources::Orders.new(@conn)
+      end
+
+      def funds
+        Resources::Funds.new(@conn)
+      end
+
+      def customers
+        Resources::Customers.new(@conn)
+      end
+
+      def status
+        Resources::Status.new(@conn)
+      end
+
+      def exchange_rates
+        Resources::ExchangeRates.new(@conn)
+      end
+
+      def choice_products
+        Resources::ChoiceProducts.new(@conn)
+      end
+
+      private
+
+      def build_connection
+        Faraday.new(url: @config.base_url, headers: default_headers) do |f|
+          f.request :url_encoded
+          f.response :follow_redirects
+          f.options.timeout = @config.timeout
+          f.options.open_timeout = @config.open_timeout
+
+          f.request :retry, retry_options
+
+          f.response :raise_error
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def default_headers
+        headers = (@config.default_headers || {}).dup
+        apply_auth(headers)
+        headers
+      end
+
+      def apply_auth(headers)
+        return unless @config.auth
+
+        @config.auth.apply(headers)
+      end
+
+      def retry_options
+        max = @config.retries[:max] || 2
+        base = @config.retries[:base] || 0.5
+        max_delay = @config.retries[:max_delay] || 5
+        {
+          max: max,
+          interval: base,
+          interval_randomness: 0.5,
+          backoff_factor: 2,
+          max_interval: max_delay,
+          retry_statuses: [429, 500, 502, 503, 504],
+          methods: %i[get head options]
+        }
+      end
+    end
+
+    # Namespace for resource-specific wrappers.
+    module Resources; end
+  end
+end

data/lib/tango/api/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Errors
+      # Base HTTP error carrying status, body, request id and optional i18n key.
+      class HttpError < StandardError
+        attr_reader :status, :body, :request_id, :i18n_key
+
+        def initialize(message, status:, body: nil, request_id: nil, i18n_key: nil)
+          super(message)
+          @status = status
+          @body = body
+          @request_id = request_id
+          @i18n_key = i18n_key
+        end
+      end
+
+      class Unauthorized < HttpError; end
+      class Forbidden < HttpError; end
+      class NotFound < HttpError; end
+      class RateLimited < HttpError; end
+      class ServerError < HttpError; end
+    end
+  end
+end

data/lib/tango/api/resources/accounts.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Client for Accounts endpoints.
+      class Accounts < Base
+        # GET /customers/{customerIdentifier}/accounts
+        def list_for_customer(customer_identifier, params = {})
+          get_json("customers/#{customer_identifier}/accounts", params)
+        end
+
+        # GET /accounts/{accountIdentifier}
+        def get(account_identifier)
+          get_json("accounts/#{account_identifier}")
+        end
+
+        # POST /customers/{customerIdentifier}/accounts
+        def create(customer_identifier, body)
+          post_json("customers/#{customer_identifier}/accounts", body)
+        end
+
+        # PATCH /customers/{customerIdentifier}/accounts/{accountIdentifier}
+        def update_under_customer(customer_identifier, account_identifier, body)
+          patch_json("customers/#{customer_identifier}/accounts/#{account_identifier}", body)
+        end
+
+        # Low balance alerts
+        # GET /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance
+        def list_low_balance_alerts(customer_identifier, account_identifier)
+          get_json("customers/#{customer_identifier}/accounts/#{account_identifier}/lowbalance")
+        end
+
+        # POST /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance
+        def set_low_balance_alert(customer_identifier, account_identifier, body)
+          post_json("customers/#{customer_identifier}/accounts/#{account_identifier}/lowbalance", body)
+        end
+
+        # GET /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance/{alertIdentifier}
+        def get_low_balance_alert(customer_identifier, account_identifier, alert_identifier)
+          path = "customers/#{customer_identifier}/accounts/#{account_identifier}/lowbalance/#{alert_identifier}"
+          get_json(path)
+        end
+
+        # PATCH /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance/{alertIdentifier}
+        def update_low_balance_alert(customer_identifier, account_identifier, alert_identifier, body)
+          path = "customers/#{customer_identifier}/accounts/#{account_identifier}/lowbalance/#{alert_identifier}"
+          patch_json(path, body)
+        end
+
+        # DELETE /customers/{customerIdentifier}/accounts/{accountIdentifier}/lowbalance/{alertIdentifier}
+        def delete_low_balance_alert(customer_identifier, account_identifier, alert_identifier)
+          path = "customers/#{customer_identifier}/accounts/#{account_identifier}/lowbalance/#{alert_identifier}"
+          delete_json(path)
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/base.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Tango
+  module Api
+    module Resources
+      # Base resource providing JSON parsing and Faraday error mapping.
+      class Base
+        def initialize(conn)
+          @conn = conn
+        end
+
+        private
+
+        def get_json(path, params = nil)
+          response = params ? @conn.get(path, params) : @conn.get(path)
+          unless (200..299).cover?(response.status)
+            error = Struct.new(:response).new({ status: response.status, body: response.body,
+                                                headers: response.headers })
+            raise map_faraday_error(error)
+          end
+          parse_json_response(response)
+        rescue Faraday::Error => e
+          raise map_faraday_error(e)
+        end
+
+        def post_json(path, body, extra_headers = nil)
+          headers = { "Content-Type" => "application/json" }
+          headers.merge!(extra_headers) if extra_headers
+          response = @conn.post(path, body.to_json, headers)
+          unless (200..299).cover?(response.status)
+            error = Struct.new(:response).new({ status: response.status, body: response.body,
+                                                headers: response.headers })
+            raise map_faraday_error(error)
+          end
+          parse_json_response(response)
+        rescue Faraday::Error => e
+          raise map_faraday_error(e)
+        end
+
+        def patch_json(path, body, extra_headers = nil)
+          headers = { "Content-Type" => "application/json" }
+          headers.merge!(extra_headers) if extra_headers
+          response = @conn.patch(path, body.to_json, headers)
+          unless (200..299).cover?(response.status)
+            error = Struct.new(:response).new({ status: response.status, body: response.body,
+                                                headers: response.headers })
+            raise map_faraday_error(error)
+          end
+          parse_json_response(response)
+        rescue Faraday::Error => e
+          raise map_faraday_error(e)
+        end
+
+        def delete_json(path)
+          response = @conn.delete(path)
+          ensure_success_or_raise(response)
+          body_text = response.body.to_s
+          return {} if body_text.strip.empty?
+
+          parse_json_response(response)
+        rescue Faraday::Error => e
+          raise map_faraday_error(e)
+        end
+
+        def ensure_success_or_raise(response)
+          return if (200..299).cover?(response.status)
+
+          error = Struct.new(:response).new({ status: response.status, body: response.body,
+                                              headers: response.headers })
+          raise map_faraday_error(error)
+        end
+
+        def parse_json_response(res)
+          JSON.parse(res.body)
+        rescue JSON::ParserError
+          { "raw" => res.body }
+        end
+
+        def map_faraday_error(error)
+          status = error.response&.dig(:status)
+          body = error.response&.dig(:body)
+          request_id = error.response&.dig(:headers, "x-request-id")
+          message, i18n_key = extract_error_message(body)
+
+          case status
+          when 401 then Errors::Unauthorized.new(message, status: status, body: body, request_id: request_id,
+                                                          i18n_key: i18n_key)
+          when 403 then Errors::Forbidden.new(message, status: status, body: body, request_id: request_id,
+                                                       i18n_key: i18n_key)
+          when 404 then Errors::NotFound.new(message, status: status, body: body, request_id: request_id,
+                                                      i18n_key: i18n_key)
+          when 429 then Errors::RateLimited.new(message, status: status, body: body, request_id: request_id,
+                                                         i18n_key: i18n_key)
+          else Errors::ServerError.new(message, status: status || 500, body: body, request_id: request_id,
+                                                i18n_key: i18n_key)
+          end
+        end
+
+        def extract_error_message(body)
+          json = begin
+            JSON.parse(body)
+          rescue StandardError
+            nil
+          end
+          return ["API Error", nil] unless json.is_a?(Hash)
+
+          [json["message"] || "API Error", json["i18nKey"]]
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/catalogs.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Client for Catalogs endpoints.
+      class Catalogs < Base
+        # GET /catalogs with flexible params
+        # Arrays are encoded as repeated keys
+        def get(params = {})
+          query = encode_arrays(params)
+          get_json("catalogs", query)
+        end
+
+        # Convenience: filter by brandKey
+        def get_by_brand_key(brand_key, params = {})
+          get(params.merge(brandKey: brand_key))
+        end
+
+        # Convenience: filter by brandName
+        def get_by_brand_name(brand_name, params = {})
+          get(params.merge(brandName: brand_name))
+        end
+
+        # Convenience: filter by utid
+        def get_by_utid(utid, params = {})
+          get(params.merge(utid: utid))
+        end
+
+        # Convenience: filter by rewardName
+        def get_by_reward_name(reward_name, params = {})
+          get(params.merge(rewardName: reward_name))
+        end
+
+        private
+
+        def encode_arrays(params)
+          params.transform_values do |v|
+            if v.is_a?(Array)
+              # Faraday will expand arrays as repeated keys when params_encoder is nil
+            end
+            v
+          end
+        end
+
+        # encode_arrays intentionally returns arrays as-is to let Faraday repeat keys
+      end
+    end
+  end
+end

data/lib/tango/api/resources/choice_products.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Resource for Choice Products catalog and details.
+      class ChoiceProducts < Base
+        # GET /choiceProducts
+        # Params may include: rewardName, currencyCode, countries: []
+        def get(params = {})
+          get_json("choiceProducts", params)
+        end
+
+        # GET /choiceProducts/{utid}
+        def get_for_utid(utid)
+          get_json("choiceProducts/#{utid}")
+        end
+
+        # GET /choiceProducts/{choiceProductUtid}/catalog
+        # Supports typical catalog query params, including filters and verbosity flags.
+        def catalog(choice_product_utid, params = {})
+          get_json("choiceProducts/#{choice_product_utid}/catalog", params)
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/customers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Client for Customers endpoints.
+      class Customers < Base
+        # GET /customers
+        def list(params = {})
+          get_json("customers", params)
+        end
+
+        # GET /customers/{customerIdentifier}
+        def get(customer_identifier)
+          get_json("customers/#{customer_identifier}")
+        end
+
+        # POST /customers
+        def create(body)
+          post_json("customers", body)
+        end
+
+        # GET /customers/{customerIdentifier}/accounts
+        def accounts(customer_identifier, params = {})
+          get_json("customers/#{customer_identifier}/accounts", params)
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/exchange_rates.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Resource for exchange rates across catalog items and currencies.
+      class ExchangeRates < Base
+        # GET /exchangerates
+        # Example params: { currency: 'USD', country: 'US' }
+        def get(params = {})
+          get_json("exchangerates", params)
+        end
+
+        # GET /exchangerates/{utid}
+        # Fetch exchange rate info for a specific catalog item by UTID.
+        def get_for_utid(utid, params = {})
+          get_json("exchangerates/#{utid}", params)
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/funds.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Client for Funds endpoints.
+      class Funds < Base
+        # GET /creditCards
+        # Optional params: { customerIdentifier:, accountIdentifier:, ... } (varies by tenant)
+        def list_cards(params = {})
+          get_json("creditCards", params)
+        end
+
+        # GET /creditCards/{creditCardToken}
+        def get_card(credit_card_token)
+          get_json("creditCards/#{credit_card_token}")
+        end
+
+        # POST /creditCards
+        def register_card(body)
+          post_json("creditCards", body)
+        end
+
+        # POST /creditCardUnregisters
+        # Body: { customerIdentifier:, accountIdentifier:, creditCardToken: }
+        def unregister_card(body)
+          post_json("creditCardUnregisters", body)
+        end
+
+        # POST /creditCardDeposits
+        # Body requires: customerIdentifier, accountIdentifier, externalRefID, creditCardToken, amount
+        def create_credit_card_deposit(body)
+          post_json("creditCardDeposits", body)
+        end
+
+        # GET /creditCardDeposits/{externalRefID}
+        def get_credit_card_deposit(external_ref_id)
+          get_json("creditCardDeposits/#{external_ref_id}")
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/orders.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Client for Orders endpoints.
+      class Orders < Base
+        # POST /orders
+        def create(body, idempotency_key: nil)
+          headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : nil
+          post_json("orders", body, headers)
+        end
+
+        # GET /orders/{referenceOrderID}
+        def get(order_id)
+          get_json("orders/#{order_id}")
+        end
+
+        # GET /orders
+        def list(params = {})
+          get_json("orders", params)
+        end
+
+        # POST /orders/{order_id}/resend
+        def resend(order_id, idempotency_key: nil)
+          headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : nil
+          post_json("orders/#{order_id}/resend", {}, headers)
+        end
+      end
+    end
+  end
+end

data/lib/tango/api/resources/status.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tango
+  module Api
+    module Resources
+      # Resource for platform/system status checks.
+      class Status < Base
+        # GET /status
+        def get
+          get_json("status")
+        end
+      end
+    end
+  end
+end

data/lib/tango/api.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "logger"
+
+module Tango
+  # Root namespace for the Tango API Ruby client.
+  module Api
+    # Configuration entry point for the Tango API client.
+    class << self
+      def configure
+        yield(configuration)
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+    end
+
+    # Holds client-wide configuration such as timeouts, retries and auth.
+    class Configuration
+      attr_accessor :base_url, :timeout, :open_timeout, :retries, :logger, :default_headers, :auth
+
+      def initialize
+        @base_url = ENV.fetch("TANGO_URL", "https://integration-api.tangocard.com/raas/v2").to_s.presence
+        @timeout = 45
+        @open_timeout = 5
+        @retries = { max: 2, base: 0.5, max_delay: 5 }
+        @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+        @default_headers = { "Accept" => "application/json" }
+        @auth = nil
+      end
+    end
+  end
+end

data/sig/tango/api/client.rbs

@@ -0,0 +1,20 @@
+module Tango
+  module Api
+    module Client
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+
+    class Client
+      def initialize: (?Configuration) -> void
+      def catalogs: Resources::Catalogs
+      def accounts: Resources::Accounts
+      def orders: Resources::Orders
+      def funds: Resources::Funds
+      def customers: Resources::Customers
+      def status: Resources::Status
+      def exchange_rates: Resources::ExchangeRates
+      def choice_products: Resources::ChoiceProducts
+    end
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: tango-api-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Puneeth Kumar DN
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Client for Tango API with Basic/OAuth2, flexible params, retries and
+  structured errors.
+email:
+- puneeth@engagedly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/tango/api.rb
+- lib/tango/api/auth/basic.rb
+- lib/tango/api/auth/oauth2.rb
+- lib/tango/api/client.rb
+- lib/tango/api/client/version.rb
+- lib/tango/api/errors.rb
+- lib/tango/api/resources/accounts.rb
+- lib/tango/api/resources/base.rb
+- lib/tango/api/resources/catalogs.rb
+- lib/tango/api/resources/choice_products.rb
+- lib/tango/api/resources/customers.rb
+- lib/tango/api/resources/exchange_rates.rb
+- lib/tango/api/resources/funds.rb
+- lib/tango/api/resources/orders.rb
+- lib/tango/api/resources/status.rb
+- sig/tango/api/client.rbs
+homepage: https://github.com/Engagedly-Inc/tango-api-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Engagedly-Inc/tango-api-client
+  source_code_uri: https://github.com/Engagedly-Inc/tango-api-client
+  changelog_uri: https://github.com/Engagedly-Inc/tango-api-client/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Ruby client for Tango (BHN) API with dual auth and robust errors.
+test_files: []