kortana-dev-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 997d5b86ba941ebf76795917ab911e7db813ec8e761fb80f46ed06491d29f968
+  data.tar.gz: 10399a24ab1a9a28ab0797b548645cbcf8c5d56eccfc8f2554a34d50f725f048
+SHA512:
+  metadata.gz: e0f3ad4b65934e278e02de90558c7072a42fe39e4e620c5756e703273b68851fbea01a818e160810ee30ea2a2bba9de70753c512f805b3a35c82c247d39246c7
+  data.tar.gz: b2dc9cfd6344c0a9dcb8d7be738a343463340a5185bbfaf0d30dba9b0c1c055580786a76cbc7a32a5a51e91f0e9f36354154c860bb171cfec151152d58f5786b

data/lib/kortana/client.rb

@@ -0,0 +1,131 @@
+module Kortana
+  class Client
+    attr_reader :blockchain, :wallets, :contracts, :payments, :merchants,
+                :banking, :cards, :compliance, :settlement
+
+    BASE_URLS = {
+      "mainnet" => "https://console.kortana.network/api/v1",
+      "testnet" => "https://console.kortana.network/api/v1"
+    }.freeze
+
+    def initialize(api_key:, environment: "mainnet", base_url: nil, timeout: 30, max_retries: 3)
+      raise ConfigurationError, "api_key must not be empty" if api_key.nil? || api_key.strip.empty?
+      raise ConfigurationError, "environment must be 'mainnet' or 'testnet'" unless %w[mainnet testnet].include?(environment)
+
+      @api_key = api_key.strip
+      @environment = environment
+      @base_url = base_url || BASE_URLS[environment]
+      @timeout = timeout
+      @max_retries = max_retries
+
+      setup_http_client
+      setup_modules
+    end
+
+    def get(path, params = {}, headers = {})
+      request(:get, path, params, nil, headers)
+    end
+
+    def post(path, body = nil, headers = {})
+      request(:post, path, nil, body, headers)
+    end
+
+    def put(path, body = nil, headers = {})
+      request(:put, path, nil, body, headers)
+    end
+
+    def delete(path, headers = {})
+      request(:delete, path, nil, nil, headers)
+    end
+
+    private
+
+    def setup_http_client
+      @conn = Faraday.new(url: @base_url) do |f|
+        f.request :url_encoded
+        
+        f.request :retry, {
+          max: @max_retries,
+          interval: 1.0,
+          backoff_factor: 2.0,
+          exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
+        }
+
+        f.options.timeout = @timeout
+        f.options.open_timeout = 5
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def setup_modules
+      require_relative 'modules/blockchain'
+      require_relative 'modules/wallets'
+      require_relative 'modules/contracts'
+      require_relative 'modules/payments'
+      require_relative 'modules/merchants'
+      require_relative 'modules/banking'
+      require_relative 'modules/cards'
+      require_relative 'modules/compliance'
+      require_relative 'modules/settlement'
+
+      @blockchain = Modules::Blockchain.new(self)
+      @wallets    = Modules::Wallets.new(self)
+      @contracts  = Modules::Contracts.new(self)
+      @payments   = Modules::Payments.new(self)
+      @merchants  = Modules::Merchants.new(self)
+      @banking    = Modules::Banking.new(self)
+      @cards      = Modules::Cards.new(self)
+      @compliance = Modules::Compliance.new(self)
+      @settlement = Modules::Settlement.new(self)
+    end
+
+    def request(method, path, params = nil, body = nil, headers = {})
+      # Auto-generate idempotency key for mutations if write operation
+      idempotency_key = headers["Idempotency-Key"]
+      if %i[post put patch].include?(method) && !idempotency_key
+        idempotency_key = "idem_#{SecureRandom.uuid}"
+      end
+
+      res = @conn.send(method) do |req|
+        req.path = path
+        req.params = params if params
+        req.headers["Authorization"] = "Bearer #{@api_key}"
+        req.headers["User-Agent"] = "kortana-sdk-ruby/1.0.0"
+        req.headers["Idempotency-Key"] = idempotency_key if idempotency_key
+        req.headers["Content-Type"] = "application/json"
+        req.body = body.to_json if body
+      end
+
+      handle_response(res)
+    rescue Faraday::Error => e
+      raise ServerError.new("Network/Faraday connection failed: #{e.message}")
+    end
+
+    def handle_response(res)
+      return JSON.parse(res.body) if res.status >= 200 && res.status < 300
+
+      begin
+        err_body = JSON.parse(res.body)
+        err_detail = err_body["error"] || {}
+        msg = err_detail["message"] || "API returned status #{res.status}"
+        code = err_detail["code"]
+        request_id = err_detail["request_id"]
+      rescue
+        msg = "API returned status #{res.status}"
+        code = nil
+        request_id = nil
+      end
+
+      error_class = case res.status
+                    when 401 then AuthError
+                    when 400 then ValidationError
+                    when 429 then RateLimitError
+                    when 404 then NotFoundError
+                    when 409 then ConflictError
+                    else ServerError
+                    end
+
+      raise error_class.new(msg, code: code, request_id: request_id, http_status: res.status)
+    end
+  end
+end

data/lib/kortana/errors.rb

@@ -0,0 +1,23 @@
+module Kortana
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  
+  class APIError < Error
+    attr_reader :code, :request_id, :http_status
+
+    def initialize(message, code: nil, request_id: nil, http_status: nil)
+      super(message)
+      @code = code
+      @request_id = request_id
+      @http_status = http_status
+    end
+  end
+
+  class AuthError < APIError; end
+  class ValidationError < APIError; end
+  class RateLimitError < APIError; end
+  class NotFoundError < APIError; end
+  class ConflictError < APIError; end
+  class ServerError < APIError; end
+  class WebhookSignatureError < Error; end
+end

data/lib/kortana/modules/banking.rb

@@ -0,0 +1,61 @@
+module Kortana
+  module Modules
+    class Banking
+      def initialize(client)
+        @client = client
+      end
+
+      def create_customer(name:, email:, phone: nil, address: nil)
+        @client.post("/banking/customers", {
+          name: name,
+          email: email,
+          phone: phone,
+          address: address
+        })
+      end
+
+      def get_customer(id)
+        @client.get("/banking/customers/#{id}")
+      end
+
+      def update_customer(id, params)
+        @client.put("/banking/customers/#{id}", params)
+      end
+
+      def list_customers(options = {})
+        @client.get("/banking/customers", options)
+      end
+
+      def create_bank_account(customer_id:, bank_name:, account_number:, routing_number:, account_type: "checking")
+        @client.post("/banking/accounts", {
+          customerId: customer_id,
+          bankName: bank_name,
+          accountNumber: account_number,
+          routingNumber: routing_number,
+          accountType: account_type
+        })
+      end
+
+      def get_bank_account(id)
+        @client.get("/banking/accounts/#{id}")
+      end
+
+      def list_bank_accounts(customer_id)
+        @client.get("/banking/accounts", { customerId: customer_id })
+      end
+
+      def create_transfer(from_address:, to_address:, amount:, currency: "USD")
+        @client.post("/banking/transfers", {
+          fromAddress: from_address,
+          toAddress: to_address,
+          amount: amount.to_s,
+          currency: currency
+        })
+      end
+
+      def get_transfer(id)
+        @client.get("/banking/transfers/#{id}")
+      end
+    end
+  end
+end

data/lib/kortana/modules/blockchain.rb

@@ -0,0 +1,48 @@
+module Kortana
+  module Modules
+    class Blockchain
+      def initialize(client)
+        @client = client
+      end
+
+      def get_block(block_number_or_hash)
+        @client.get("/blockchain/blocks/#{block_number_or_hash}")
+      end
+
+      def get_transaction(tx_hash)
+        @client.get("/blockchain/transactions/#{tx_hash}")
+      end
+
+      def get_transaction_receipt(tx_hash)
+        @client.get("/blockchain/transactions/#{tx_hash}/receipt")
+      end
+
+      def get_gas_price
+        res = @client.get("/blockchain/gas-price")
+        res["gasPrice"].to_i
+      end
+
+      def estimate_gas(params)
+        res = @client.post("/blockchain/estimate-gas", params)
+        res["gasLimit"].to_i
+      end
+
+      def get_network_status
+        @client.get("/blockchain/status")
+      end
+
+      def get_logs(filter)
+        @client.post("/blockchain/logs", filter)
+      end
+
+      def get_validators
+        @client.get("/blockchain/validators")
+      end
+
+      def get_token_balance(address, token_address)
+        res = @client.get("/blockchain/addresses/#{address}/token-balance", { token: token_address })
+        res["balance"].to_i
+      end
+    end
+  end
+end

data/lib/kortana/modules/cards.rb

@@ -0,0 +1,48 @@
+module Kortana
+  module Modules
+    class Cards
+      def initialize(client)
+        @client = client
+      end
+
+      def create(customer_id: nil, merchant_id: nil, type: "virtual", currency: "DNR", spend_limit: nil, metadata: nil)
+        @client.post("/cards", {
+          customerId: customer_id,
+          merchantId: merchant_id,
+          type: type,
+          currency: currency,
+          spendLimit: spend_limit ? spend_limit.to_s : nil,
+          metadata: metadata
+        })
+      end
+
+      def get(id)
+        @client.get("/cards/#{id}")
+      end
+
+      def list(options = {})
+        @client.get("/cards", options)
+      end
+
+      def update_controls(id, controls)
+        @client.put("/cards/#{id}/controls", controls)
+      end
+
+      def disable(id)
+        @client.post("/cards/#{id}/disable")
+      end
+
+      def enable(id)
+        @client.post("/cards/#{id}/enable")
+      end
+
+      def simulate_transaction(card_id:, amount:, merchant: nil)
+        @client.post("/cards/simulate", {
+          cardId: card_id,
+          amount: amount.to_s,
+          merchant: merchant
+        })
+      end
+    end
+  end
+end

data/lib/kortana/modules/compliance.rb

@@ -0,0 +1,61 @@
+module Kortana
+  module Modules
+    class Compliance
+      def initialize(client)
+        @client = client
+      end
+
+      def create_kyc(customer_id: nil, merchant_id: nil, document_type:, document_country:, document_front:, document_back: nil, selfie: nil)
+        @client.post("/compliance/kyc", {
+          customerId: customer_id,
+          merchantId: merchant_id,
+          documentType: document_type,
+          documentCountry: document_country,
+          documentFront: document_front,
+          documentBack: document_back,
+          selfie: selfie
+        })
+      end
+
+      def get_kyc(id)
+        @client.get("/compliance/kyc/#{id}")
+      end
+
+      def create_kyb(merchant_id:, business_name:, business_type:, tax_id: nil, documents: nil)
+        @client.post("/compliance/kyb", {
+          merchantId: merchant_id,
+          businessName: business_name,
+          businessType: business_type,
+          taxId: tax_id,
+          documents: documents
+        })
+      end
+
+      def get_kyb(id)
+        @client.get("/compliance/kyb/#{id}")
+      end
+
+      def screen(entity_id: nil, transaction_id: nil, first_name: nil, last_name: nil, dob: nil)
+        @client.post("/compliance/screen", {
+          entityId: entity_id,
+          transactionId: transaction_id,
+          firstName: first_name,
+          lastName: last_name,
+          dob: dob
+        })
+      end
+
+      def get_screening(id)
+        @client.get("/compliance/screen/#{id}")
+      end
+
+      def create_str(transaction_id:, reason:, evidence: nil)
+        @client.post("/compliance/str", {
+          transactionId: transaction_id,
+          reason: reason,
+          evidence: evidence
+        })
+      end
+    end
+  end
+end

data/lib/kortana/modules/contracts.rb

@@ -0,0 +1,62 @@
+module Kortana
+  module Modules
+    class Contracts
+      def initialize(client)
+        @client = client
+      end
+
+      def deploy_contract(abi:, bytecode:, args: nil)
+        @client.post("/contracts/deploy", {
+          abi: abi,
+          bytecode: bytecode,
+          args: args
+        })
+      end
+
+      def read_contract(address, abi, method, args = [])
+        res = @client.post("/contracts/#{address}/read", {
+          abi: abi,
+          method: method,
+          args: args
+        })
+        res["result"]
+      end
+
+      def write_contract(address, abi, method, args = [], options = {})
+        @client.post("/contracts/#{address}/write", {
+          abi: abi,
+          method: method,
+          args: args,
+          options: options
+        })
+      end
+
+      def estimate_contract_gas(address, abi, method, args = [], options = {})
+        res = @client.post("/contracts/#{address}/estimate-gas", {
+          abi: abi,
+          method: method,
+          args: args,
+          options: options
+        })
+        res["gasLimit"].to_i
+      end
+
+      def get_contract_events(address, abi, event_name, filter = {})
+        @client.post("/contracts/#{address}/events", {
+          abi: abi,
+          eventName: event_name,
+          filter: filter
+        })
+      end
+
+      def verify_contract(address, source_code:, compiler_version:, optimizer: false, optimizer_runs: 200)
+        @client.post("/contracts/#{address}/verify", {
+          sourceCode: source_code,
+          compilerVersion: compiler_version,
+          optimizer: optimizer,
+          optimizerRuns: optimizer_runs
+        })
+      end
+    end
+  end
+end

data/lib/kortana/modules/merchants.rb

@@ -0,0 +1,62 @@
+module Kortana
+  module Modules
+    class Merchants
+      def initialize(client)
+        @client = client
+      end
+
+      def create(name:, email:, business_name: nil, metadata: nil)
+        @client.post("/merchants", {
+          name: name,
+          email: email,
+          businessName: business_name,
+          metadata: metadata
+        })
+      end
+
+      def get(id)
+        @client.get("/merchants/#{id}")
+      end
+
+      def update(id, params)
+        @client.put("/merchants/#{id}", params)
+      end
+
+      def list_stores(merchant_id)
+        @client.get("/merchants/#{merchant_id}/stores")
+      end
+
+      def create_store(merchant_id, name:, currency: "DNR", settlement_currency: "DNR")
+        @client.post("/merchants/#{merchant_id}/stores", {
+          name: name,
+          currency: currency,
+          settlementCurrency: settlement_currency
+        })
+      end
+
+      def list_terminals(merchant_id)
+        @client.get("/merchants/#{merchant_id}/terminals")
+      end
+
+      def create_terminal(merchant_id, name: nil, store_id: nil, location: nil)
+        @client.post("/merchants/#{merchant_id}/terminals", {
+          name: name,
+          storeId: store_id,
+          location: location
+        })
+      end
+
+      def create_api_key(merchant_id, name:, permissions:, expires_at: nil)
+        @client.post("/merchants/#{merchant_id}/api-keys", {
+          name: name,
+          permissions: permissions,
+          expiresAt: expires_at
+        })
+      end
+
+      def list_api_keys(merchant_id)
+        @client.get("/merchants/#{merchant_id}/api-keys")
+      end
+    end
+  end
+end

data/lib/kortana/modules/payments.rb

@@ -0,0 +1,60 @@
+module Kortana
+  module Modules
+    class Payments
+      def initialize(client)
+        @client = client
+      end
+
+      def create_intent(amount:, currency: "DNR", description: nil, customer_id: nil, merchant_id: nil, metadata: nil)
+        @client.post("/payments/intents", {
+          amount: amount.to_s,
+          currency: currency,
+          description: description,
+          customerId: customer_id,
+          merchantId: merchant_id,
+          metadata: metadata
+        })
+      end
+
+      def get_intent(id)
+        @client.get("/payments/intents/#{id}")
+      end
+
+      def confirm_intent(id, payment_method = nil)
+        @client.post("/payments/intents/#{id}/confirm", {
+          paymentMethod: payment_method
+        })
+      end
+
+      def cancel_intent(id)
+        @client.post("/payments/intents/#{id}/cancel")
+      end
+
+      def create_invoice(items:, customer: nil, due_date: nil, metadata: nil)
+        @client.post("/payments/invoices", {
+          items: items,
+          customer: customer,
+          dueDate: due_date,
+          metadata: metadata
+        })
+      end
+
+      def get_invoice(id)
+        @client.get("/payments/invoices/#{id}")
+      end
+
+      def create_payment_link(amount:, currency: "DNR", description: nil, expires_at: nil)
+        @client.post("/payments/links", {
+          amount: amount.to_s,
+          currency: currency,
+          description: description,
+          expiresAt: expires_at
+        })
+      end
+
+      def get_payment_link(id)
+        @client.get("/payments/links/#{id}")
+      end
+    end
+  end
+end

data/lib/kortana/modules/settlement.rb

@@ -0,0 +1,22 @@
+module Kortana
+  module Modules
+    class Settlement
+      def initialize(client)
+        @client = client
+      end
+
+      def get_treasury(currency: nil)
+        params = currency ? { currency: currency } : {}
+        @client.get("/settlement/treasury", params)
+      end
+
+      def list(options = {})
+        @client.get("/settlement/settlements", options)
+      end
+
+      def get(id)
+        @client.get("/settlement/settlements/#{id}")
+      end
+    end
+  end
+end

data/lib/kortana/modules/wallets.rb

@@ -0,0 +1,39 @@
+module Kortana
+  module Modules
+    class Wallets
+      def initialize(client)
+        @client = client
+      end
+
+      def get_balance
+        @client.get("/wallets/balance")
+      end
+
+      def list_addresses
+        @client.get("/wallets/addresses")
+      end
+
+      def get_address(index = nil)
+        params = index ? { index: index } : {}
+        @client.get("/wallets/address", params)
+      end
+
+      def transfer(to:, amount:, currency: "DNR", chain: nil)
+        @client.post("/wallets/transfers", {
+          to: to,
+          amount: amount.to_s,
+          currency: currency,
+          chain: chain
+        })
+      end
+
+      def list_transactions(options = {})
+        @client.get("/wallets/transactions", options)
+      end
+
+      def get_transaction(id)
+        @client.get("/wallets/transactions/#{id}")
+      end
+    end
+  end
+end

data/lib/kortana/version.rb

@@ -0,0 +1,3 @@
+module Kortana
+  VERSION = "1.0.0"
+end

data/lib/kortana/webhooks.rb

@@ -0,0 +1,33 @@
+module Kortana
+  class Webhook
+    def initialize(secret)
+      @secret = secret
+    end
+
+    def verify(payload, signature)
+      raise WebhookSignatureError, "Signature must not be empty" if signature.nil? || signature.strip.empty?
+      raise WebhookSignatureError, "Webhook secret must not be empty" if @secret.nil? || @secret.strip.empty?
+
+      expected = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), @secret, payload)
+
+      unless secure_compare(expected, signature)
+        raise WebhookSignatureError, "Webhook signature verification failed"
+      end
+
+      JSON.parse(payload)
+    rescue JSON::ParserError
+      raise WebhookSignatureError, "Invalid JSON payload"
+    end
+
+    private
+
+    # Constant time comparison to avoid timing attacks
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+      l = a.unpack("C*")
+      res = 0
+      b.each_byte { |val| res |= val ^ l.shift }
+      res.zero?
+    end
+  end
+end

data/lib/kortana.rb

@@ -0,0 +1,14 @@
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+require 'openssl'
+require 'securerandom'
+
+require_relative 'kortana/version'
+require_relative 'kortana/errors'
+require_relative 'kortana/client'
+require_relative 'kortana/webhooks'
+
+module Kortana
+  # Entry point configuration module
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: kortana-dev-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kortana Labs
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+description: Integrate with Kortana Pay, wallets, smart contracts, card issuance,
+  compliance, and ledger APIs directly from Ruby applications.
+email:
+- engineering@kortana.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/kortana.rb
+- lib/kortana/client.rb
+- lib/kortana/errors.rb
+- lib/kortana/modules/banking.rb
+- lib/kortana/modules/blockchain.rb
+- lib/kortana/modules/cards.rb
+- lib/kortana/modules/compliance.rb
+- lib/kortana/modules/contracts.rb
+- lib/kortana/modules/merchants.rb
+- lib/kortana/modules/payments.rb
+- lib/kortana/modules/settlement.rb
+- lib/kortana/modules/wallets.rb
+- lib/kortana/version.rb
+- lib/kortana/webhooks.rb
+homepage: https://docs.kortana.io/sdk/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.kortana.io/sdk/ruby
+  source_code_uri: https://gitlab.com/emeka.iwuagwu/kortanablockchain-hub
+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: 4.0.10
+specification_version: 4
+summary: Official Ruby SDK for the Kortana Blockchain Platform
+test_files: []