genius_referrals 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c34a1d0205f298289eed4ce89eb837e18a5405c644c003c77c83215ffbabc03f
+  data.tar.gz: 654890ad79e62b41413ee18a61919f4f69dbfb794f7e98fbb210c1097df1bb0a
+SHA512:
+  metadata.gz: c30024498ceae4d664ed86b9aa884679f537a52bb9db2c8df88c6b9c61ec54a7d59c2d083cd41e710d9de1da77c3492b51eb656683976fa5e15d28266cb4be8c
+  data.tar.gz: 54fea89f16a36c671bc0faa52330f34db88417e80c12d4cbec9e6c536fb551f1218c8339c78eac21806da987fe92c801fdc698f3903f848c81223891cf16bf40

data/LICENSE

@@ -0,0 +1,28 @@
+License: 
+========
+The MIT License (MIT)
+http://opensource.org/licenses/MIT
+
+Copyright (c) 2014 - 2016 APIMATIC Limited
+
+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.
+
+Trade Mark:
+==========
+APIMATIC is a trade mark for APIMATIC Limited

data/README.md

@@ -0,0 +1,134 @@
+# Genius Referrals Ruby SDK
+
+Official Ruby SDK for the Genius Referrals public API.
+
+This rebuild is based on the accepted public API contract matrix from
+`alainhl/gr-agent-led-dev-delivery#14` and is the first implementation slice for
+`GeniusReferrals/Genius-Referrals-RUBY#2`.
+
+## Install
+
+```bash
+gem install genius_referrals
+```
+
+For local validation from this repository:
+
+```bash
+gem build genius_referrals.gemspec
+gem install ./genius_referrals-0.1.0.gem
+```
+
+## Authentication
+
+The API uses the `X-Auth-Token` header. The SDK redacts the token from exception
+request snapshots and never includes it in error messages.
+
+```ruby
+require 'genius_referrals'
+
+client = GeniusReferrals::Client.new(auth_token: 'gr_live_or_test_token')
+result = client.authentications.test
+puts result.data
+```
+
+The default base URL is `https://api.geniusreferrals.com`.
+
+## Resource Examples
+
+List advocates:
+
+```ruby
+page = client.advocates.list('my-account', page: 1, limit: 25)
+
+page.results.each do |advocate|
+  puts [advocate['token'], advocate['email']].compact.join(' ')
+end
+```
+
+Create an advocate with the accepted wrapper:
+
+```ruby
+client.advocates.create(
+  'my-account',
+  {
+    name: 'Ada',
+    lastname: 'Lovelace',
+    email: 'ada@example.com'
+  }
+)
+```
+
+Patch a bonus with unwrapped partial fields:
+
+```ruby
+client.bonuses.patch('my-account', 1234, status: 'approved')
+```
+
+Call a report:
+
+```ruby
+client.reports.revenue(
+  account_slug: 'my-account',
+  start_date: '2026-01-01',
+  end_date: '2026-01-31'
+)
+```
+
+## Pagination
+
+Collection helpers return a `GeniusReferrals::Page` object when the response
+uses the standard `limit`, `page`, `total`, and `results` shape.
+
+```ruby
+client.advocates.each('my-account', limit: 100) do |advocate|
+  process(advocate)
+end
+```
+
+The SDK preserves API parameter names from the accepted matrix: `page` is sent
+as `page`, and `limit` is sent as `limit`.
+
+## Errors
+
+The SDK raises typed exceptions:
+
+- `GeniusReferrals::AuthenticationError` for HTTP `401`
+- `GeniusReferrals::AuthorizationError` for HTTP `403`
+- `GeniusReferrals::NotFoundError` for HTTP `404`
+- `GeniusReferrals::ConflictError` for HTTP `409`
+- `GeniusReferrals::ValidationError` for HTTP `400` and `422`
+- `GeniusReferrals::RateLimitError` for HTTP `429`
+- `GeniusReferrals::APIError` for other non-success responses
+- `GeniusReferrals::TransportError` for local network or serialization failures
+
+All API errors include `status_code`, parsed `response`, raw body text when
+available, and redacted request details.
+
+## Guarded Integration Test
+
+Integration tests are opt-in so CI and local development do not use real
+credentials by accident:
+
+```bash
+GR_SDK_RUN_INTEGRATION=1 GR_API_TOKEN=... ruby -Itest test/integration/authentication_test.rb
+```
+
+Do not print or commit the token.
+
+## Package Validation
+
+This ticket does not publish to RubyGems. Validate the candidate locally with:
+
+```bash
+ruby -Itest test/client_test.rb test/resources_test.rb
+ruby -c lib/genius_referrals.rb
+gem build genius_referrals.gemspec
+sha256sum genius_referrals-0.1.0.gem
+```
+
+Current candidate version: `0.1.0`.
+
+Rollback/removal if an unpublished candidate is bad: delete the local gem from
+the repository root, fix the branch, rebuild, and replace the PR evidence.
+Public RubyGems publication requires Ledger risk review and Alain approval.

data/lib/genius_referrals/client.rb

@@ -0,0 +1,169 @@
+require 'json'
+require 'uri'
+
+module GeniusReferrals
+  DEFAULT_BASE_URL = 'https://api.geniusreferrals.com'
+  RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504].freeze
+
+  class Client
+    attr_reader :auth_token, :base_url, :timeout, :max_retries, :backoff_factor,
+                :transport, :user_agent
+
+    # Client for the Genius Referrals public API.
+    #
+    # @param auth_token [String] API token sent as `X-Auth-Token`.
+    # @param base_url [String] API origin. Defaults to production.
+    # @param timeout [Numeric] Request timeout in seconds.
+    # @param max_retries [Integer] Retry budget for transient errors.
+    # @param backoff_factor [Numeric] Initial exponential backoff delay.
+    # @param transport [Object] Optional test/custom transport.
+    def initialize(auth_token:, base_url: DEFAULT_BASE_URL, timeout: 30, max_retries: 2,
+                   backoff_factor: 0.25, transport: nil,
+                   user_agent: "geniusreferrals-ruby/#{VERSION}")
+      raise ArgumentError, 'auth_token is required' if auth_token.to_s.empty?
+
+      @auth_token = auth_token
+      @base_url = base_url.to_s.sub(%r{/+\z}, '')
+      @timeout = timeout
+      @max_retries = max_retries
+      @backoff_factor = backoff_factor
+      @transport = transport || NetHTTPTransport.new
+      @user_agent = user_agent
+
+      @accounts = AccountsResource.new(self)
+      @advocates = AdvocatesResource.new(self)
+      @authentications = AuthenticationsResource.new(self)
+      @bonuses = BonusesResource.new(self)
+      @campaigns = CampaignsResource.new(self)
+      @products = ProductsResource.new(self)
+      @redemption_requests = RedemptionRequestsResource.new(self)
+      @referrals = ReferralsResource.new(self)
+      @reports = ReportsResource.new(self)
+      @root = RootResource.new(self)
+      @tags = TagsResource.new(self)
+      @utilities = UtilitiesResource.new(self)
+      @vouchers = VouchersResource.new(self)
+      @widgets_packages = WidgetsPackagesResource.new(self)
+    end
+
+    attr_reader :accounts, :advocates, :authentications, :bonuses, :campaigns,
+                :products, :redemption_requests, :referrals, :reports, :root,
+                :tags, :utilities, :vouchers, :widgets_packages
+
+    # Send a request to an API path and return parsed response content.
+    def request(method, path, params: nil, json: nil)
+      request = build_request(method, path, params: params, json: json)
+      attempt = 0
+
+      loop do
+        begin
+          response = transport.request(
+            request[:method],
+            request[:url],
+            headers: request[:headers],
+            body: request[:body],
+            timeout: timeout
+          )
+        rescue StandardError => e
+          raise TransportError, e.message if attempt >= max_retries
+
+          sleep_for_retry(attempt)
+          attempt += 1
+          next
+        end
+
+        return parse_success(response.status_code, response.body) if response.status_code < 400
+
+        if RETRYABLE_STATUS_CODES.include?(response.status_code) && attempt < max_retries
+          sleep_for_retry(attempt)
+          attempt += 1
+          next
+        end
+
+        parsed = parse_json(response.body)
+        error_class = ERROR_BY_STATUS.fetch(response.status_code, APIError)
+        raise error_class.new(
+          error_message(response.status_code, parsed, response.body),
+          status_code: response.status_code,
+          response: parsed,
+          body: response.body,
+          request: request,
+          secrets: [auth_token]
+        )
+      end
+    end
+
+    # Build an authenticated JSON request hash.
+    def build_request(method, path, params: nil, json: nil)
+      clean_path = path.start_with?('/') ? path : "/#{path}"
+      url = "#{base_url}#{clean_path}#{query_string(params || {})}"
+      body = json.nil? ? nil : JSON.generate(json)
+      headers = {
+        'Accept' => 'application/json',
+        'User-Agent' => user_agent,
+        'X-Auth-Token' => auth_token
+      }
+      headers['Content-Type'] = 'application/json' unless json.nil?
+
+      { method: method.to_s.upcase, url: url, headers: headers, body: body }
+    end
+
+    private
+
+    def query_string(params)
+      pairs = []
+      params.each do |key, value|
+        next if value.nil?
+
+        if value.is_a?(Array)
+          value.each { |item| pairs << [key, item] }
+        else
+          pairs << [key, value]
+        end
+      end
+      pairs.empty? ? '' : "?#{URI.encode_www_form(pairs)}"
+    end
+
+    def parse_success(status_code, body)
+      return nil if status_code == 204 || body.to_s.empty?
+
+      parse_json(body)
+    end
+
+    def parse_json(body)
+      return nil if body.to_s.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def error_message(status_code, parsed, body)
+      if parsed.is_a?(Hash)
+        message = parsed['message'] || parsed['error']
+        return "Genius Referrals API error #{status_code}: #{message}" if message
+      end
+      return "Genius Referrals API error #{status_code}" unless body.to_s.empty?
+
+      "Genius Referrals API error #{status_code}: empty response"
+    end
+
+    def sleep_for_retry(attempt)
+      delay = backoff_factor * (2**attempt)
+      sleep(delay) if delay.positive?
+    end
+  end
+
+  # Backward-compatible class name for callers of the older generated gem.
+  class GeniusReferralsClient < Client
+    def initialize(content_type = 'application/json', x_auth_token = nil, **options)
+      if content_type.is_a?(Hash)
+        options = content_type.merge(options)
+      end
+
+      x_auth_token = options.delete(:x_auth_token) || options.delete('x_auth_token') || x_auth_token
+      token = options.delete(:auth_token) || x_auth_token
+      super(auth_token: token, **options)
+    end
+  end
+end

data/lib/genius_referrals/errors.rb

@@ -0,0 +1,84 @@
+module GeniusReferrals
+  SENSITIVE_HEADER_NAMES = ['authorization', 'x-auth-token'].freeze
+  SENSITIVE_FIELD_FRAGMENTS = ['api_key', 'apikey', 'authorization', 'password', 'secret', 'token'].freeze
+
+  # Returns a redacted deep copy for objects that may contain credentials.
+  def self.redact(value, secrets: [])
+    secret_values = Array(secrets).compact.map(&:to_s).reject(&:empty?)
+    case value
+    when Hash
+      value.each_with_object({}) do |(key, item), redacted|
+        lowered = key.to_s.downcase
+        redacted[key] = if sensitive_key?(lowered)
+                          '[REDACTED]'
+                        else
+                          redact(item, secrets: secret_values)
+                        end
+      end
+    when Array
+      value.map { |item| redact(item, secrets: secret_values) }
+    when String
+      redact_string(value, secret_values)
+    else
+      value
+    end
+  end
+
+  def self.sensitive_key?(key)
+    SENSITIVE_HEADER_NAMES.include?(key) ||
+      SENSITIVE_FIELD_FRAGMENTS.any? { |fragment| key.include?(fragment) }
+  end
+
+  def self.redact_string(value, secrets)
+    secrets.reduce(value.dup) do |text, secret|
+      text.gsub(secret, '[REDACTED]')
+    end
+  end
+
+  class Error < StandardError
+  end
+
+  class TransportError < Error
+  end
+
+  class APIError < Error
+    attr_reader :status_code, :response, :body, :request
+
+    def initialize(message, status_code:, response: nil, body: nil, request: nil, secrets: [])
+      redacted_message = GeniusReferrals.redact(message, secrets: secrets)
+      super(redacted_message)
+      @status_code = status_code
+      @response = GeniusReferrals.redact(response, secrets: secrets)
+      @body = GeniusReferrals.redact(body, secrets: secrets)
+      @request = GeniusReferrals.redact(request || {}, secrets: secrets)
+    end
+  end
+
+  class AuthenticationError < APIError
+  end
+
+  class AuthorizationError < APIError
+  end
+
+  class NotFoundError < APIError
+  end
+
+  class ConflictError < APIError
+  end
+
+  class ValidationError < APIError
+  end
+
+  class RateLimitError < APIError
+  end
+
+  ERROR_BY_STATUS = {
+    400 => ValidationError,
+    401 => AuthenticationError,
+    403 => AuthorizationError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    422 => ValidationError,
+    429 => RateLimitError
+  }.freeze
+end

data/lib/genius_referrals/resource.rb

@@ -0,0 +1,49 @@
+require 'uri'
+
+module GeniusReferrals
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    attr_reader :client
+
+    def request(method, path, params: nil, json: nil)
+      APIResponse.from_api(client.request(method, path, params: params, json: json))
+    end
+
+    def page(method, path, params: nil)
+      Page.from_api(client.request(method, path, params: params))
+    end
+
+    def each_page(path, page_number: 1, limit: 100, params: nil)
+      return enum_for(:each_page, path, page_number: page_number, limit: limit, params: params) unless block_given?
+
+      current = page_number
+      loop do
+        response = page('GET', path, params: compact((params || {}).merge(page: current, limit: limit)))
+        response.results.each { |item| yield item }
+        break if response.total.nil? || response.results.empty?
+        break if current * limit >= response.total.to_i
+
+        current += 1
+      end
+    end
+
+    def compact(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key] = value unless value.nil?
+      end
+    end
+
+    def wrapped(name, payload)
+      { name => payload.to_h }
+    end
+
+    def esc(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

data/lib/genius_referrals/resources/accounts.rb

@@ -0,0 +1,13 @@
+module GeniusReferrals
+  class AccountsResource < Resource
+    # List accounts with standard page/limit pagination.
+    def list(page: 1, limit: 10, filter: nil, sort: nil)
+      page('GET', '/accounts', params: compact(page: page, limit: limit, filter: filter, sort: sort))
+    end
+
+    # Retrieve one account by slug.
+    def retrieve(account_slug)
+      request('GET', "/accounts/#{esc(account_slug)}")
+    end
+  end
+end

data/lib/genius_referrals/resources/advocates.rb

@@ -0,0 +1,85 @@
+module GeniusReferrals
+  class AdvocatesResource < Resource
+    # List advocates for an account.
+    def list(account_slug, page: 1, limit: 10, filter: nil, sort: nil, **filters)
+      params = compact({ page: page, limit: limit, filter: filter, sort: sort }.merge(filters))
+      page('GET', "/accounts/#{esc(account_slug)}/advocates", params: params)
+    end
+
+    # Iterate advocates across all available pages.
+    def each(account_slug, page_number: 1, limit: 100, **filters, &block)
+      each_page("/accounts/#{esc(account_slug)}/advocates",
+                page_number: page_number,
+                limit: limit,
+                params: filters,
+                &block)
+    end
+
+    # Create an advocate using the accepted `advocate` wrapper.
+    def create(account_slug, advocate)
+      request('POST', "/accounts/#{esc(account_slug)}/advocates", json: wrapped('advocate', advocate))
+    end
+
+    # Retrieve one advocate by token.
+    def retrieve(account_slug, advocate_token)
+      request('GET', "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}")
+    end
+
+    # Replace an advocate using the accepted `advocate` wrapper.
+    def update(account_slug, advocate_token, advocate)
+      request('PUT',
+              "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}",
+              json: wrapped('advocate', advocate))
+    end
+
+    # Patch an advocate with unwrapped partial fields.
+    def patch(account_slug, advocate_token, **fields)
+      request('PATCH', "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}", json: fields)
+    end
+
+    # Delete one advocate.
+    def delete(account_slug, advocate_token)
+      request('DELETE', "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}")
+    end
+
+    # Delete all advocates for an account, or a scoped comma-separated token set.
+    def delete_all(account_slug, advocates: nil)
+      query_value = advocates.is_a?(Array) ? advocates.join(',') : advocates
+      request('DELETE',
+              "/accounts/#{esc(account_slug)}/advocates",
+              params: compact(advocates: query_value))
+    end
+
+    # Return share links for one advocate.
+    def share_links(account_slug, advocate_token)
+      request('GET', "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}/share-links")
+    end
+
+    # List payment methods for one advocate.
+    def payment_methods(account_slug, advocate_token, page: 1, limit: 10)
+      page('GET',
+           "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}/payment-methods",
+           params: { page: page, limit: limit })
+    end
+
+    # Create an advocate payment method.
+    def create_payment_method(account_slug, advocate_token, payment_method)
+      request('POST',
+              "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}/payment-methods",
+              json: wrapped('advocate_payment_method', payment_method))
+    end
+
+    # Retrieve one advocate payment method.
+    def retrieve_payment_method(account_slug, advocate_token, payment_method_id)
+      request('GET',
+              "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}/payment-methods/#{esc(payment_method_id)}")
+    end
+
+    # Replace one advocate payment method.
+    def update_payment_method(account_slug, advocate_token, payment_method_id, payment_method)
+      request('PUT',
+              "/accounts/#{esc(account_slug)}/advocates/#{esc(advocate_token)}/payment-methods/#{esc(payment_method_id)}",
+              json: wrapped('advocate_payment_method', payment_method))
+    end
+  end
+end

data/lib/genius_referrals/resources/authentications.rb

@@ -0,0 +1,8 @@
+module GeniusReferrals
+  class AuthenticationsResource < Resource
+    # Call `/test-authentication` with the configured token.
+    def test
+      request('GET', '/test-authentication')
+    end
+  end
+end

data/lib/genius_referrals/resources/bonuses.rb

@@ -0,0 +1,63 @@
+module GeniusReferrals
+  class BonusesResource < Resource
+    # List bonuses for an account.
+    def list(account_slug, page: 1, limit: 10, filter: nil, sort: nil, **filters)
+      params = compact({ page: page, limit: limit, filter: filter, sort: sort }.merge(filters))
+      page('GET', "/accounts/#{esc(account_slug)}/bonuses", params: params)
+    end
+
+    # Create a bonus using the `bonus` wrapper.
+    def create(account_slug, bonus)
+      request('POST', "/accounts/#{esc(account_slug)}/bonuses", json: wrapped('bonus', bonus))
+    end
+
+    # Create a forced bonus using the `bonus` wrapper.
+    def force(account_slug, bonus)
+      request('POST', "/accounts/#{esc(account_slug)}/bonuses/force", json: wrapped('bonus', bonus))
+    end
+
+    # Simulate bonus eligibility with API query parameters.
+    def checkup(account_slug, **params)
+      request('GET', "/accounts/#{esc(account_slug)}/bonuses/checkup", params: params)
+    end
+
+    # List bonus request traces.
+    def traces(account_slug, page: 1, limit: 10, **params)
+      page('GET',
+           "/accounts/#{esc(account_slug)}/bonuses/traces",
+           params: compact({ page: page, limit: limit }.merge(params)))
+    end
+
+    # Retrieve one bonus request trace.
+    def retrieve_trace(account_slug, trace_id)
+      request('GET', "/accounts/#{esc(account_slug)}/bonuses/traces/#{esc(trace_id)}")
+    end
+
+    # Retrieve one bonus.
+    def retrieve(account_slug, bonus_id)
+      request('GET', "/accounts/#{esc(account_slug)}/bonuses/#{esc(bonus_id)}")
+    end
+
+    # Patch a bonus with unwrapped partial fields.
+    def patch(account_slug, bonus_id, **fields)
+      request('PATCH', "/accounts/#{esc(account_slug)}/bonuses/#{esc(bonus_id)}", json: fields)
+    end
+
+    # Delete one bonus.
+    def delete(account_slug, bonus_id)
+      request('DELETE', "/accounts/#{esc(account_slug)}/bonuses/#{esc(bonus_id)}")
+    end
+
+    # Attach a tag to a bonus using the live-doc `bonus.tag.slug` shape.
+    def add_tag(account_slug, bonus_id, tag_slug)
+      request('POST',
+              "/accounts/#{esc(account_slug)}/bonuses/#{esc(bonus_id)}/tags",
+              json: { 'bonus' => { 'tag' => { 'slug' => tag_slug } } })
+    end
+
+    # Remove one tag from a bonus.
+    def remove_tag(account_slug, bonus_id, tag_slug)
+      request('DELETE', "/accounts/#{esc(account_slug)}/bonuses/#{esc(bonus_id)}/tags/#{esc(tag_slug)}")
+    end
+  end
+end

data/lib/genius_referrals/resources/campaigns.rb

@@ -0,0 +1,15 @@
+module GeniusReferrals
+  class CampaignsResource < Resource
+    # List campaigns for an account.
+    def list(account_slug, page: 1, limit: 10, filter: nil, sort: nil)
+      page('GET',
+           "/accounts/#{esc(account_slug)}/campaigns",
+           params: compact(page: page, limit: limit, filter: filter, sort: sort))
+    end
+
+    # Retrieve one campaign.
+    def retrieve(account_slug, campaign_slug)
+      request('GET', "/accounts/#{esc(account_slug)}/campaigns/#{esc(campaign_slug)}")
+    end
+  end
+end