kody-clientsdk-ruby 1.6.14 → 1.6.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a8bb43a172f7c0200dfcfcdea60904a5c4afed9f3a5c18c9762c0f2381370fe
-  data.tar.gz: 4a0cfbae738e945b5ad5f9b8fdbc63c41bc62367d52ba1501ab267eac2086253
+  metadata.gz: 7ec4860466627d2a80a8ff0cc97908ff9a89a9eaef21002a816e00b0e421a20f
+  data.tar.gz: aa58a62425ca75939731d86f741328c51ec9215cea10963788c510be3bf02015
 SHA512:
-  metadata.gz: cda9d9d04bace30d567c6fd8bcff3a161ad5016ad899aca89736f1c0068b30cc1fd69507f0f0bef8d7fe305aeda7739f652a2b0a20f8497b6db24b59a493fec3
-  data.tar.gz: f4fc9af1179eb5ce3d192ca76b18c06f9a66d41f83544758910199d2e47336749198632a66ac9f958c182d84060dcaf67bd47074d360393f14aa92668e0b380f
+  metadata.gz: f5c5d70939c8db2e42b516eb120c310ae7d376d51c2653655728baffe73846fb30d86fba1bc1338a35593e0c19514a07b81312c4959d3057c12886551bf8e8f4
+  data.tar.gz: 7d4fbf3c253b5050ed057d57fa10594cf2b74452890afaad6d147e5e52d4a133b3d9b8eafeb03ed67c0f74daf9eb8dfcac082ead2d181c03ea631063d372bda1

data/README.md

@@ -1,211 +1,128 @@
 # Kody API - Ruby SDK
 
-This guide provides an overview of using the Kody API and its reference documentation for Ruby.
+This guide provides an overview of using the Kody API and its reference documentation.
 
-- [Installation](#installation)
+- [Client Libraries](#client-libraries)
+- [Ruby Installation](#ruby-installation)
 - [Authentication](#authentication)
-- [Quick Start](#quick-start)
+- [Documentation](#documentation)
 - [Sample code](#sample-code)
 
-## Installation
+## Client Libraries
 
-Add this line to your application's Gemfile:
+Kody provides client libraries for many popular languages to access the APIs. If your desired programming language is supported by the client libraries, we recommend that you use this option.
 
-```ruby
-gem 'kody-clientsdk-ruby'
-```
+Available languages:
+- Java: https://github.com/KodyPay/kody-clientsdk-java/
+- Python: https://github.com/KodyPay/kody-clientsdk-python/
+- PHP: https://github.com/KodyPay/kody-clientsdk-php/
+- .Net: https://github.com/KodyPay/kody-clientsdk-dotnet/
+- Ruby: https://github.com/KodyPay/kody-clientsdk-ruby/
 
-And then execute:
+The advantages of using the Kody Client library instead of a REST API are:
+- Maintained by Kody.
+- Built-in authentication and increased security.
+- Built-in retries.
+- Idiomatic for each language.
+- Quicker development.
+- Backwards compatibility with new versions.
 
-```bash
-bundle install
-```
+If your coding language is not listed, please let the Kody team know and we will be able to create it for you.
 
-Or install it yourself as:
+## Ruby Installation
+### Requirements
+- Ruby 2.6.10 and above
+- Bundler (optional), recommended way to manage dependencies
+
+Install the Kody Ruby Client SDK using gem:
 
 ```bash
 gem install kody-clientsdk-ruby
 ```
 
-### Requirements
-- Ruby 2.6.10 or higher
-- gRPC support
-
-## Authentication
-
-The client library uses a combination of a `Store ID` and an `API key`.
-These will be shared with you during the technical integration onboarding or by your Kody contact.
-
-During development, you will have access to a **test Store** and **test API key**, and when the integration is ready for live access, the production credentials will be shared securely with you and associated with a live store that was onboarded on Kody.
-
-The test and live API calls are always compatible, only changing credentials and the service hostname is required to enable the integration in production.
-
-### Host names
-
-- Development and test: `grpc-staging.kodypay.com`
-- Live: `grpc.kodypay.com`
-
-## Quick Start
+Or add to your Gemfile:
 
 ```ruby
-require 'kody'
-
-# Configure the Kody client
-Kody.configure do |config|
-  config.api_key = 'your-api-key'
-  config.store_id = 'your-store-id'
-  config.staging! # Use staging environment for testing
-end
-
-# Create a client instance
-client = Kody::Client.new
-
-# Initiate a payment
-begin
-  response = client.ecom.initiate_payment(
-    payment_reference: Kody::EcomClient.generate_payment_reference,
-    amount_minor_units: 2000, # £20.00 in pence
-    currency: 'GBP',
-    order_id: Kody::EcomClient.generate_order_id,
-    return_url: 'https://your-website.com/payment-return'
-  )
-
-  puts "Payment initiated successfully!"
-  puts "Payment ID: #{response.response.payment_id}"
-  puts "Payment URL: #{response.response.payment_url}"
-
-rescue Kody::Error => e
-  puts "Error: #{e.message}"
-rescue GRPC::BadStatus => e
-  puts "gRPC Error: #{e.message}"
-end
+gem 'kody-clientsdk-ruby'
 ```
 
-## Configuration Options
+The library can also be downloaded from [RubyGems](https://rubygems.org/gems/kody-clientsdk-ruby).
 
-### Environment Configuration
+### Import in code
 
 ```ruby
-# Production environment (default)
-Kody.configure do |config|
-  config.api_key = 'your-production-api-key'
-  config.store_id = 'your-production-store-id'
-  # config.host defaults to 'grpc.kodypay.com'
-end
-
-# Staging environment
-Kody.configure do |config|
-  config.api_key = 'your-test-api-key'
-  config.store_id = 'your-test-store-id'
-  config.staging! # Sets host to 'grpc-staging.kodypay.com'
-end
+require 'kody'
 
-# Local development
+# Configure SDK
 Kody.configure do |config|
+  config.staging_ap!  # Use Asia-Pacific staging
   config.api_key = 'your-api-key'
   config.store_id = 'your-store-id'
-  config.development! # Sets host to 'localhost:8080' with TLS disabled
 end
-```
-
-### Environment Variables
 
-You can also configure using environment variables:
+# eCommerce API
+ecom_stub = Com::Kodypay::Grpc::Ecom::V1::KodyEcomPaymentsService::Stub.new(
+  Kody.configuration.endpoint,
+  GRPC::Core::ChannelCredentials.new
+)
 
-```bash
-export KODY_API_KEY="your-api-key"
-export KODY_STORE_ID="your-store-id"
-```
+# Terminal API
+terminal_stub = Com::Kodypay::Grpc::Pay::V1::KodyPayTerminalService::Stub.new(
+  Kody.configuration.endpoint,
+  GRPC::Core::ChannelCredentials.new
+)
 
-```ruby
-Kody.configure do |config|
-  config.api_key = ENV['KODY_API_KEY']
-  config.store_id = ENV['KODY_STORE_ID']
-  config.staging! # or production/development
-end
+# Ordering API
+ordering_stub = Com::Kodypay::Grpc::Ordering::V1::KodyOrderingService::Stub.new(
+  Kody.configuration.endpoint,
+  GRPC::Core::ChannelCredentials.new
+)
 ```
 
-## Available Methods
-
-### E-commerce Payments
-
-#### Initiate Payment
+## Authentication
 
-```ruby
-response = client.ecom.initiate_payment(
-  payment_reference: 'unique-payment-ref',
-  amount_minor_units: 2000, # Amount in minor units (e.g., pence for GBP)
-  currency: 'GBP',
-  order_id: 'order-123',
-  return_url: 'https://your-site.com/payment-return',
-  # Optional parameters:
-  order_metadata: '{"item": "Product Name"}',
-  expiry: {
-    show_timer: true,
-    expiring_seconds: 1800 # 30 minutes
-  },
-  locale: 'en_GB',
-  show_order_summary: true,
-  show_merchant_name: true
-)
-```
+The client library uses a combination of a `Store ID` and an `API key`.
+These will be shared with you during the technical integration onboarding or by your Kody contact.
 
-#### Get Payments
+During development, you will have access to a **test Store** and **test API key**, and when the integration is ready for live access, the production credentials will be shared securely with you and associated with a live store that was onboarded on Kody.
 
-```ruby
-response = client.ecom.get_payments(
-  page: 1,
-  page_size: 10,
-  # Optional filter:
-  filter: {
-    order_id: 'specific-order-id'  # Optional: filter by order ID
-  }
-)
+The test and live API calls are always compatible, only changing credentials and the service hostname is required to enable the integration in production.
 
-puts "Total payments: #{response.response.total}"
-response.response.payments.each do |payment|
-  puts "Payment ID: #{payment.payment_id}"
-  puts "Status: #{payment.status}"
-  puts "Amount: #{payment.sale_data.amount_minor_units}" if payment.has_sale_data?
-end
-```
+### Host names
 
-**Note:** Currently, `initiate_payment` and `get_payments` methods are implemented. Additional methods (payment details, refunds, etc.) will be added in future versions.
+Development and Test:
+- Default: `grpc-staging.kodypay.com`
+- For Asia-specific region: `grpc-staging-ap.kodypay.com`
+- For Europe-specific region: `grpc-staging-eu.kodypay.com`
 
-## Helper Methods
+Live:
+- Default: `grpc.kodypay.com`
+- For Asia-specific region: `grpc-ap.kodypay.com`
+- For Europe-specific region: `grpc-eu.kodypay.com`
 
-The SDK provides convenient helper methods:
+### Endpoints Configuration
 
 ```ruby
-# Generate unique payment reference
-payment_ref = Kody::EcomClient.generate_payment_reference
-# Returns: "pay_a1b2c3d4e5f6g7h8"
-
-# Generate unique order ID
-order_id = Kody::EcomClient.generate_order_id  
-# Returns: "order_a1b2c3d4e5f6g7h8"
+# Production
+config.production!      # grpc.kodypay.com:443
+config.production_ap!   # grpc-ap.kodypay.com:443  
+config.production_eu!   # grpc-eu.kodypay.com:443
+
+# Staging  
+config.staging!         # grpc-staging.kodypay.com:443
+config.staging_ap!      # grpc-staging-ap.kodypay.com:443
+config.staging_eu!      # grpc-staging-eu.kodypay.com:443
 ```
 
-## Sample code
-
-Complete examples can be found in the `samples/` directory:
-
-- [Initiate Payment](samples/ecom/initiate_payment.rb)
-- [Get Payments](samples/ecom/get_payments.rb)
-
 ## Documentation
 
 For complete API documentation, examples, and integration guides, please visit:
 📚 https://api-docs.kody.com
 
-## Development Status
-
-This is a minimal initial version of the Ruby SDK focusing on the core payment initiation functionality. The SDK follows the same patterns as other Kody client SDKs and will be extended with additional features in future releases.
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/KodyPay/kody-clientsdk-ruby.
-
-## License
+## Sample code
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+- Java: https://github.com/KodyPay/kody-clientsdk-java/tree/main/samples
+- Python: https://github.com/KodyPay/kody-clientsdk-python/tree/main/versions/3_12/samples
+- PHP: https://github.com/KodyPay/kody-clientsdk-php/tree/main/samples
+- .Net: https://github.com/KodyPay/kody-clientsdk-dotnet/tree/main/samples
+- Ruby: https://github.com/KodyPay/kody-clientsdk-ruby/tree/main/samples

data/lib/kody/configuration.rb

@@ -1,8 +1,15 @@
 module Kody
   class Configuration
-    # Common KodyPay gRPC endpoints
-    PRODUCTION_ENDPOINT = 'grpc.kodypay.com:443'
-    STAGING_ENDPOINT = 'grpc-staging-ap.kodypay.com:443'
+    # KodyPay gRPC endpoints by region
+    # Production endpoints
+    PRODUCTION_ENDPOINT = 'grpc.kodypay.com:443'          # Default
+    PRODUCTION_AP_ENDPOINT = 'grpc-ap.kodypay.com:443'    # Asia-Pacific
+    PRODUCTION_EU_ENDPOINT = 'grpc-eu.kodypay.com:443'    # Europe
+    
+    # Staging endpoints  
+    STAGING_ENDPOINT = 'grpc-staging.kodypay.com:443'     # Default
+    STAGING_AP_ENDPOINT = 'grpc-staging-ap.kodypay.com:443' # Asia-Pacific
+    STAGING_EU_ENDPOINT = 'grpc-staging-eu.kodypay.com:443' # Europe
 
     attr_accessor :api_key, :store_id, :endpoint
 
@@ -13,5 +20,25 @@ module Kody
     def staging!
       @endpoint = STAGING_ENDPOINT
     end
+
+    def staging_ap!
+      @endpoint = STAGING_AP_ENDPOINT
+    end
+
+    def staging_eu!
+      @endpoint = STAGING_EU_ENDPOINT
+    end
+
+    def production!
+      @endpoint = PRODUCTION_ENDPOINT
+    end
+
+    def production_ap!
+      @endpoint = PRODUCTION_AP_ENDPOINT
+    end
+
+    def production_eu!
+      @endpoint = PRODUCTION_EU_ENDPOINT
+    end
   end
 end

data/lib/kody/version.rb

@@ -1,3 +1,3 @@
 module Kody
-  VERSION = "1.6.14"
+  VERSION = "1.6.16"
 end

data/samples/ecom/get_payments.rb

@@ -10,25 +10,31 @@ puts
 # Configuration - replace with your actual credentials
 api_key = ENV['KODY_API_KEY'] || 'your-api-key-here'
 store_id = ENV['KODY_STORE_ID'] || 'your-store-id-here'
-endpoint = ENV['KODY_ENDPOINT'] || 'grpc-staging-ap.kodypay.com:443'
-
-puts "📡 Endpoint: #{endpoint}"
-puts "🔑 Store ID: #{store_id[0..8]}..."
-puts "🗝️ API Key: #{api_key[0..10]}..."
-puts
 
 begin
   # Require the published gem
   require 'kody'
 
-  # Create the stub and make the API call
+  # Configure KodyPay SDK
+  Kody.configure do |config|
+    config.staging_ap!  # Use Asia-Pacific staging endpoint
+    config.api_key = api_key
+    config.store_id = store_id
+  end
+
+  puts "📡 Endpoint: #{Kody.configuration.endpoint}"
+  puts "🔑 Store ID: #{Kody.configuration.store_id[0..8]}..."
+  puts "🗝️ API Key: #{Kody.configuration.api_key[0..10]}..."
+  puts
+
+  # Create the stub using configuration
   stub = Com::Kodypay::Grpc::Ecom::V1::KodyEcomPaymentsService::Stub.new(
-    endpoint,
+    Kody.configuration.endpoint,
     GRPC::Core::ChannelCredentials.new
   )
 
   request = Com::Kodypay::Grpc::Ecom::V1::GetPaymentsRequest.new(
-    store_id: store_id,
+    store_id: Kody.configuration.store_id,
     page_cursor: Com::Kodypay::Grpc::Ecom::V1::GetPaymentsRequest::PageCursor.new(
       page: 1,
       page_size: 10
@@ -36,7 +42,7 @@ begin
   )
 
   puts "📤 Making gRPC call to GetPayments API..."
-  response = stub.get_payments(request, metadata: { 'x-api-key' => api_key })
+  response = stub.get_payments(request, metadata: { 'x-api-key' => Kody.configuration.api_key })
 
   puts "🎉 SUCCESS! Response from KodyPay API:"
   puts "📊 Total payments: #{response.response.total}"

data/samples/pos/get_terminals.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+
+puts "🚀 KodyPay Ruby SDK Sample - GetTerminals API"
+puts "============================================="
+puts "📦 Using kody-clientsdk-ruby gem from RubyGems"
+puts
+
+# Configuration - replace with your actual credentials
+api_key = ENV['KODY_API_KEY'] || 'your-api-key-here'
+store_id = ENV['KODY_STORE_ID'] || 'your-store-id-here'
+
+begin
+  # Require the published gem
+  require 'kody'
+
+  # Configure KodyPay SDK
+  Kody.configure do |config|
+    config.staging_ap!  # Use Asia-Pacific staging endpoint
+    config.api_key = api_key
+    config.store_id = store_id
+  end
+
+  puts "📡 Endpoint: #{Kody.configuration.endpoint}"
+  puts "🔑 Store ID: #{Kody.configuration.store_id[0..8]}..."
+  puts "🗝️ API Key: #{Kody.configuration.api_key[0..10]}..."
+  puts
+
+  # Create the Terminal API stub using configuration
+  stub = Com::Kodypay::Grpc::Pay::V1::KodyPayTerminalService::Stub.new(
+    Kody.configuration.endpoint,
+    GRPC::Core::ChannelCredentials.new
+  )
+
+  request = Com::Kodypay::Grpc::Pay::V1::TerminalsRequest.new(
+    store_id: Kody.configuration.store_id
+  )
+
+  puts "📤 Making gRPC call to GetTerminals API..."
+  response = stub.terminals(request, metadata: { 'x-api-key' => Kody.configuration.api_key })
+
+  puts "🎉 SUCCESS! Response from KodyPay Terminal API:"
+  puts "🖥️ Total terminals: #{response.terminals.length}"
+
+  if response.terminals.empty?
+    puts "📭 No terminals found for this store"
+  else
+    response.terminals.each_with_index do |terminal, index|
+      status = terminal.online ? "🟢 Online" : "🔴 Offline"
+      puts "\n🖥️ Terminal #{index + 1}:"
+      puts "   ID: #{terminal.terminal_id}"
+      puts "   Status: #{status}"
+      
+      if terminal.respond_to?(:last_activity_at) && terminal.last_activity_at
+        last_activity = Time.at(terminal.last_activity_at.seconds).strftime('%Y-%m-%d %H:%M:%S')
+        puts "   Last Activity: #{last_activity}"
+      end
+      
+      if terminal.respond_to?(:version) && terminal.version && !terminal.version.empty?
+        puts "   Version: #{terminal.version}"
+      end
+    end
+  end
+
+rescue GRPC::BadStatus => e
+  puts "❌ gRPC API Error: #{e.code} - #{e.message}"
+  puts "💡 Check your API credentials and store permissions"
+rescue LoadError => e
+  puts "❌ Missing dependency: #{e.message}"
+  puts "💡 Install the gem with: gem install kody-clientsdk-ruby"
+rescue => e
+  puts "❌ Error: #{e.message}"
+  puts "🔍 #{e.backtrace.first}"
+end
+
+puts "\n📚 Documentation:"
+puts "   RubyGems: https://rubygems.org/gems/kody-clientsdk-ruby"
+puts "   GitHub: https://github.com/KodyPay/kody-clientsdk-ruby"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kody-clientsdk-ruby
 version: !ruby/object:Gem::Version
-  version: 1.6.14
+  version: 1.6.16
 platform: ruby
 authors:
 - Kody Tech Team
@@ -134,6 +134,7 @@ files:
 - lib/pay_pb.rb
 - lib/pay_services_pb.rb
 - samples/ecom/get_payments.rb
+- samples/pos/get_terminals.rb
 homepage: https://github.com/KodyPay/kody-clientsdk-ruby
 licenses:
 - MIT