huntrecht-sdk 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e4418b148d7b59618906b0442001104999f4360ca3db315780d71a90091ff70
+  data.tar.gz: 47c6491f815275c4264bc80168bfe41b9be706efdeafbfd8ffecf63cdf5746ae
+SHA512:
+  metadata.gz: ecd9cb91da37da60a6c29796d3787257b8521d9f0ac8aa4b21652608c467ca3fbc6e2d1b1bb1aa39824e84632e6eb46adb6aed5bbee5c88a6e95d1f7e6ad31ee
+  data.tar.gz: d32a334f3e8dea757f1e782927d06eba5bafac6f58e56d2433fe63e860adb01f6d2eeabf8e9628e53b55df8f6d68df954b8afc0b70e9b6309a059bb3dd412b23

data/README.md

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Huntrecht SDK for Ruby
+
+Official Ruby client for the Huntrecht Platform API v1.
+
+## Installation
+
+```bash
+gem install huntrecht-sdk
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "huntrecht-sdk"
+```
+
+## Usage
+
+```ruby
+require "huntrecht"
+
+client = Huntrecht::Client.new(
+  client_id: "hnt_your_client_id",
+  client_secret: "your_secret"
+)
+
+orders = client.orders.list(status: "pending")
+```
+
+See the [Ruby SDK docs](https://huntrecht.com/docs/sdks/ruby) for the full reference.

data/lib/huntrecht/client.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "errors"
+require_relative "version"
+
+module Huntrecht
+  API_VERSION = "v1"
+  DEFAULT_BASE_URL = "https://api.huntrecht.com"
+  USER_AGENT = "huntrecht-sdk-ruby/#{VERSION}"
+
+  # Client for the Huntrecht Platform API v1.
+  #
+  #   client = Huntrecht::Client.new(
+  #     client_id: "hnt_abc123",
+  #     client_secret: "secret"
+  #   )
+  #   client.auth.token # authenticate
+  #   orders = client.orders.list
+  class Client
+    attr_reader :base_url, :client_id, :timeout, :max_retries, :retry_backoff
+    attr_accessor :access_token
+
+    def initialize(base_url: nil, client_id: nil, client_secret: nil,
+                   access_token: nil, timeout: 30, max_retries: 3,
+                   retry_backoff: 1.0)
+      @base_url = (base_url || ENV["HUNTRECHT_BASE_URL"] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @client_id = client_id || ENV["HUNTRECHT_CLIENT_ID"] || ""
+      @client_secret = client_secret || ENV["HUNTRECHT_CLIENT_SECRET"] || ""
+      @access_token = access_token
+      @refresh_token = nil
+      @token_expires_at = Time.at(0)
+      @timeout = timeout
+      @max_retries = max_retries
+      @retry_backoff = retry_backoff
+
+      require_relative "resources"
+      @auth = Resources::AuthAPI.new(self)
+      @clients = Resources::ClientsAPI.new(self)
+      @orders = Resources::OrdersAPI.new(self)
+      @payments = Resources::PaymentsAPI.new(self)
+      @subscriptions = Resources::SubscriptionsAPI.new(self)
+      @credit = Resources::CreditAPI.new(self)
+      @credit_risk = Resources::CreditRiskAPI.new(self)
+      @kyc = Resources::KycAPI.new(self)
+      @quotes = Resources::QuotesAPI.new(self)
+      @users = Resources::UsersAPI.new(self)
+      @storefront = Resources::StorefrontAPI.new(self)
+      @price_drops = Resources::PriceDropsAPI.new(self)
+      @app_proxy = Resources::AppProxyAPI.new(self)
+      @linked_payments = Resources::LinkedPaymentsAPI.new(self)
+    end
+
+    attr_reader :auth, :clients, :orders, :payments, :subscriptions,
+                :credit, :credit_risk, :kyc, :quotes, :users, :storefront,
+                :price_drops, :app_proxy, :linked_payments
+
+    def client_secret
+      @client_secret
+    end
+
+    def refresh_token
+      @refresh_token
+    end
+
+    def store_tokens(data)
+      @access_token = data["access_token"]
+      @refresh_token = data["refresh_token"]
+      @token_expires_at = Time.now + (data["expires_in"] || 1800).to_i - 60
+    end
+
+    # Make an API request with automatic auth, retry, and rate-limit handling.
+    def request(method, path, params: nil, json: nil, headers: nil, auth_required: true)
+      ensure_token if auth_required
+
+      last_error = nil
+      (0..@max_retries).each do |attempt|
+        begin
+          return perform(method, path, params: params, json: json,
+                         headers: headers, auth_required: auth_required)
+        rescue RateLimitError => e
+          last_error = e
+          raise if attempt >= @max_retries
+
+          wait = e.retry_after.positive? ? e.retry_after : @retry_backoff * (2**attempt)
+          sleep(wait)
+        rescue APIError
+          raise
+        rescue StandardError => e
+          last_error = APIError.new("HTTP error: #{e.message}")
+          raise last_error if attempt >= @max_retries
+
+          sleep(@retry_backoff * (2**attempt))
+        end
+      end
+      raise(last_error || APIError.new("Request failed"))
+    end
+
+    # Build the full URI for a path + query params (no network).
+    def build_uri(path, params = nil)
+      uri = URI("#{@base_url}/api/#{API_VERSION}#{path}")
+      clean = (params || {}).reject { |_k, v| v.nil? }
+      unless clean.empty?
+        uri.query = URI.encode_www_form(clean.map { |k, v| [k.to_s, v.to_s] })
+      end
+      uri
+    end
+
+    private
+
+    def ensure_token
+      return if @access_token && Time.now < @token_expires_at
+
+      if !@client_id.empty? && !@client_secret.empty?
+        data = @auth.token
+        store_tokens(data)
+      else
+        raise AuthenticationError, "No access token and no client credentials. " \
+                                   "Set HUNTRECHT_CLIENT_ID and HUNTRECHT_CLIENT_SECRET, " \
+                                   "or pass them to Huntrecht::Client.new."
+      end
+    end
+
+    def perform(method, path, params:, json:, headers:, auth_required:)
+      uri = build_uri(path, params)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      req_class = {
+        "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post,
+        "PUT" => Net::HTTP::Put, "PATCH" => Net::HTTP::Patch,
+        "DELETE" => Net::HTTP::Delete
+      }.fetch(method.upcase) { raise APIError, "Unsupported method #{method}" }
+
+      req = req_class.new(uri.request_uri)
+      req["Accept"] = "application/json"
+      req["User-Agent"] = USER_AGENT
+      req["Authorization"] = "Bearer #{@access_token}" if auth_required && @access_token
+      (headers || {}).each { |k, v| req[k] = v }
+      if json
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(json)
+      end
+
+      handle_response(http.request(req))
+    end
+
+    def handle_response(resp)
+      return {} if resp.code == "204"
+
+      data = begin
+        JSON.parse(resp.body || "")
+      rescue JSON::ParserError
+        { "raw" => resp.body.to_s }
+      end
+
+      case resp.code.to_i
+      when 200..299
+        data
+      when 401
+        @access_token = nil
+        raise AuthenticationError.new(data["error_description"] || "Authentication failed",
+                                      status_code: 401, response: data)
+      when 403
+        raise PermissionError.new(data["error_description"] || "Insufficient permissions",
+                                  status_code: 403, response: data)
+      when 404
+        raise NotFoundError.new(data["error_description"] || "Resource not found",
+                                status_code: 404, response: data)
+      when 422
+        raise ValidationError.new(data["error_description"] || "Validation failed",
+                                  status_code: 422, response: data)
+      when 429
+        retry_after = resp["Retry-After"].to_i
+        retry_after = 60 if retry_after <= 0
+        raise RateLimitError.new(data["error_description"] || "Rate limit exceeded",
+                                 status_code: 429, retry_after: retry_after, response: data)
+      else
+        raise APIError.new(data["error_description"] || "HTTP #{resp.code}",
+                           status_code: resp.code.to_i, response: data)
+      end
+    end
+  end
+end

data/lib/huntrecht/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Huntrecht
+  # Base error for all Huntrecht API failures.
+  class APIError < StandardError
+    attr_reader :status_code, :response
+
+    def initialize(message = nil, status_code: nil, response: nil)
+      super(message)
+      @status_code = status_code
+      @response = response
+    end
+  end
+
+  # 401 — missing, expired, or invalid credentials.
+  class AuthenticationError < APIError; end
+
+  # 403 — authenticated but not permitted.
+  class PermissionError < APIError; end
+
+  # 404 — resource not found.
+  class NotFoundError < APIError; end
+
+  # 422 — request validation failed.
+  class ValidationError < APIError; end
+
+  # 429 — rate limited. Carries the Retry-After seconds.
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = nil, status_code: 429, retry_after: 60, response: nil)
+      super(message, status_code: status_code, response: response)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/huntrecht/resources.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Huntrecht
+  module Resources
+    # Base class for all API resources.
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def request(method, path, **kwargs)
+        @client.request(method, path, **kwargs)
+      end
+
+      def page_params(page, per_page, status = nil)
+        params = { page: page, per_page: per_page }
+        params[:status] = status if status
+        params
+      end
+
+      # Accept a body as positional hash, kwargs, or both (Ruby 3
+      # separates the two at call sites, so support each style).
+      def body_for(data = nil, **kwargs)
+        body = {}
+        body.merge!(data) if data
+        kwargs.each { |k, v| body[k.to_s] = v }
+        body
+      end
+    end
+
+    # OAuth2 token lifecycle.
+    class AuthAPI < Base
+      def token(grant_type: "client_credentials", client_id: nil, client_secret: nil,
+                refresh_token: nil, scope: nil)
+        body = { "grant_type" => grant_type }
+        if grant_type == "client_credentials"
+          body["client_id"] = client_id || @client.client_id
+          body["client_secret"] = client_secret || @client.client_secret
+          body["scope"] = scope if scope
+        elsif grant_type == "refresh_token"
+          body["refresh_token"] = refresh_token || @client.refresh_token || ""
+        end
+        data = request("POST", "/auth/token", json: body, auth_required: false)
+        @client.store_tokens(data)
+        data
+      end
+
+      def revoke(token = nil)
+        tok = token || @client.access_token || ""
+        request("POST", "/auth/revoke", params: { token: tok }, auth_required: false)
+      end
+    end
+
+    # OAuth2 API clients.
+    class ClientsAPI < Base
+      def list(user_id)
+        request("GET", "/clients", params: { user_id: user_id })
+      end
+
+      def create(user_id, data = nil, **kwargs)
+        request("POST", "/clients", params: { user_id: user_id },
+                                    json: body_for(data, **kwargs))
+      end
+
+      def update(user_id, client_id, data = nil, **kwargs)
+        request("PATCH", "/clients/#{client_id}", params: { user_id: user_id },
+                                                   json: body_for(data, **kwargs))
+      end
+
+      def rotate_secret(user_id, client_id)
+        request("POST", "/clients/#{client_id}/rotate", params: { user_id: user_id })
+      end
+
+      def delete(user_id, client_id)
+        request("DELETE", "/clients/#{client_id}", params: { user_id: user_id })
+      end
+    end
+
+    # B2B trade orders.
+    class OrdersAPI < Base
+      def list(page: 1, per_page: 20, status: nil)
+        request("GET", "/orders", params: page_params(page, per_page, status))
+      end
+
+      def get(order_id)
+        request("GET", "/orders/#{order_id}")
+      end
+
+      def create(commodity:, quantity:, delivery_terms: "FOB", destination: nil, currency: "USD")
+        params = { commodity: commodity, quantity: quantity,
+                   delivery_terms: delivery_terms, currency: currency }
+        params[:destination] = destination if destination
+        request("POST", "/orders", params: params)
+      end
+    end
+
+    # Payments.
+    class PaymentsAPI < Base
+      def list(page: 1, per_page: 20, status: nil)
+        request("GET", "/payments", params: page_params(page, per_page, status))
+      end
+
+      def get(payment_id)
+        request("GET", "/payments/#{payment_id}")
+      end
+
+      def create(data = nil, **kwargs)
+        request("POST", "/payments", json: body_for(data, **kwargs))
+      end
+    end
+
+    # B2B subscriptions.
+    class SubscriptionsAPI < Base
+      def list(page: 1, per_page: 20, status: nil, include_payment_history: false)
+        params = page_params(page, per_page, status)
+        params[:include_payment_history] = include_payment_history
+        request("GET", "/subscriptions", params: params)
+      end
+
+      def get(subscription_id)
+        request("GET", "/subscriptions/#{subscription_id}")
+      end
+    end
+
+    # Basic credit scoring.
+    class CreditAPI < Base
+      def assess(data = nil, **kwargs)
+        request("POST", "/credit/assess", json: body_for(data, **kwargs))
+      end
+
+      def score(customer_email)
+        request("GET", "/credit/score/#{customer_email}")
+      end
+    end
+
+    # Risk scoring, company assessments, improvement, credit history.
+    class CreditRiskAPI < Base
+      def get_score(customer_id)
+        request("GET", "/credit-risk/score", params: { customer_id: customer_id })
+      end
+
+      def assess(data = nil, **kwargs)
+        request("POST", "/credit-risk/assess", json: body_for(data, **kwargs))
+      end
+
+      def get_history(customer_id, limit: 20)
+        request("GET", "/data-connect/credit-history",
+                params: { customer_id: customer_id, limit: limit })
+      end
+
+      def get_assessment(user_id)
+        request("GET", "/company/credit-assessment", params: { user_id: user_id })
+      end
+
+      def request_assessment(data = nil, **kwargs)
+        request("POST", "/company/credit-assessment/request", json: body_for(data, **kwargs))
+      end
+
+      def get_improvement_options
+        request("GET", "/credit-improvement/available-options")
+      end
+
+      def connect_wallet(data = nil, **kwargs)
+        request("POST", "/credit-improvement/connect-wallet", json: body_for(data, **kwargs))
+      end
+
+      def apply_boosts(data = nil, **kwargs)
+        request("POST", "/credit-improvement/apply-boosts", json: body_for(data, **kwargs))
+      end
+    end
+
+    # KYC submissions.
+    class KycAPI < Base
+      def list(page: 1, per_page: 20, status: nil)
+        request("GET", "/kyc", params: page_params(page, per_page, status))
+      end
+
+      def get(submission_id)
+        request("GET", "/kyc/#{submission_id}")
+      end
+
+      def submit(data = nil, **kwargs)
+        request("POST", "/kyc", json: body_for(data, **kwargs))
+      end
+    end
+
+    # Commodity quotes.
+    class QuotesAPI < Base
+      def list(page: 1, per_page: 20)
+        request("GET", "/quotes", params: { page: page, per_page: per_page })
+      end
+
+      def get(quote_id)
+        request("GET", "/quotes/#{quote_id}")
+      end
+
+      def create(data = nil, **kwargs)
+        request("POST", "/quotes", json: body_for(data, **kwargs))
+      end
+    end
+
+    # User profiles.
+    class UsersAPI < Base
+      def me
+        request("GET", "/users/me")
+      end
+
+      def get(user_id)
+        request("GET", "/users/#{user_id}")
+      end
+    end
+
+    # Shopify-backed catalog.
+    class StorefrontAPI < Base
+      def collections(first: 20, include_products: false)
+        first = 100 if first > 100
+        request("GET", "/storefront/collections",
+                params: { first: first, include_products: include_products })
+      end
+
+      def collection(handle, products_first: 20)
+        products_first = 250 if products_first > 250
+        request("GET", "/storefront/collections/#{handle}",
+                params: { products_first: products_first })
+      end
+
+      def products(first: 20, after: nil, b2b_only: false)
+        first = 100 if first > 100
+        params = { first: first, b2b_only: b2b_only }
+        params[:after] = after if after
+        request("GET", "/storefront/products", params: params)
+      end
+
+      def product(handle)
+        request("GET", "/storefront/products/#{handle}")
+      end
+
+      def search(query, first: 10, b2b_only: false)
+        first = 50 if first > 50
+        request("GET", "/storefront/search",
+                params: { query: query, first: first, b2b_only: b2b_only })
+      end
+    end
+
+    # Price-drop events (public).
+    class PriceDropsAPI < Base
+      def list(limit: 10, min_discount: 5.0, days: 7)
+        limit = 50 if limit > 50
+        request("GET", "/price-drops",
+                params: { limit: limit, min_discount: min_discount, days: days },
+                auth_required: false)
+      end
+
+      def featured(limit: 10)
+        limit = 10 if limit > 10
+        request("GET", "/price-drops/featured", params: { limit: limit },
+                                                auth_required: false)
+      end
+    end
+
+    # Theme-safe proxy endpoints (public).
+    class AppProxyAPI < Base
+      def collections(first: 20, signature: nil)
+        first = 100 if first > 100
+        params = { first: first }
+        params[:signature] = signature if signature
+        request("GET", "/app-proxy/collections", params: params, auth_required: false)
+      end
+
+      def collection(handle, first: 20, signature: nil)
+        first = 250 if first > 250
+        params = { first: first }
+        params[:signature] = signature if signature
+        request("GET", "/app-proxy/collections/#{handle}", params: params,
+                                                             auth_required: false)
+      end
+
+      def price_drops(limit: 10, min_discount: 5.0)
+        limit = 20 if limit > 20
+        request("GET", "/app-proxy/price-drops",
+                params: { limit: limit, min_discount: min_discount },
+                auth_required: false)
+      end
+
+      def payment_methods(customer_id: nil, product_price: 0, b2b_exclusive: false,
+                          signature: nil)
+        params = { product_price: product_price, b2b_exclusive: b2b_exclusive }
+        params[:customer_id] = customer_id if customer_id
+        params[:signature] = signature if signature
+        request("GET", "/app-proxy/payment-methods", params: params,
+                                                      auth_required: false)
+      end
+    end
+
+    # Linked wallets and bank accounts.
+    class LinkedPaymentsAPI < Base
+      def check_eligibility(customer_id, product_price: 0, b2b_exclusive: false)
+        request("GET", "/linked-payments/check-eligibility",
+                params: { customer_id: customer_id, product_price: product_price,
+                          b2b_exclusive: b2b_exclusive },
+                auth_required: false)
+      end
+
+      def link_wallet(customer_id, wallet_address: nil, wallet_provider: nil)
+        body = { "customer_id" => customer_id }
+        body["wallet_address"] = wallet_address if wallet_address
+        body["wallet_provider"] = wallet_provider if wallet_provider
+        request("POST", "/linked-payments/link-wallet", json: body)
+      end
+
+      def link_bank(customer_id, plaid_access_token: nil, account_id: nil)
+        body = { "customer_id" => customer_id }
+        body["plaid_access_token"] = plaid_access_token if plaid_access_token
+        body["account_id"] = account_id if account_id
+        request("POST", "/linked-payments/link-bank", json: body)
+      end
+
+      def linked_accounts(customer_id)
+        request("GET", "/linked-payments/linked-accounts/#{customer_id}")
+      end
+    end
+  end
+end

data/lib/huntrecht/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Huntrecht
+  VERSION = "0.1.4"
+end

data/lib/huntrecht.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Huntrecht Platform SDK for Ruby.
+#
+# Official client for the Huntrecht Platform API v1.
+#
+#   require "huntrecht"
+#
+#   client = Huntrecht::Client.new(
+#     client_id: "hnt_your_client_id",
+#     client_secret: "your_secret"
+#   )
+#   orders = client.orders.list
+require_relative "huntrecht/version"
+require_relative "huntrecht/errors"
+require_relative "huntrecht/client"

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: huntrecht-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Huntrecht
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-17 00:00:00.000000000 Z
+dependencies: []
+description: B2B commerce, credit risk, KYC, quotes, storefront, and payments for
+  the Huntrecht Platform API v1.
+email:
+- dev@huntrecht.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/huntrecht.rb
+- lib/huntrecht/client.rb
+- lib/huntrecht/errors.rb
+- lib/huntrecht/resources.rb
+- lib/huntrecht/version.rb
+homepage: https://github.com/huntrecht/sdks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/huntrecht/sdks
+  source_code_uri: https://github.com/huntrecht/sdks
+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.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Huntrecht Platform API v1
+test_files: []