data-and-reporting-sdk 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '029daa034be160955c29be965509aadc2b080bfb587f24225b26b144b774b258'
-  data.tar.gz: 1c7f87bb1def847aba87695075112c83f91414b7998d1d55f313c61af7fc28b4
+  metadata.gz: 6721542a03c25fde2867c8819966d572e40239f74641037d6e971723228bf665
+  data.tar.gz: 8d0e17cadf7651a4081b3947c1e7fc7599352866855d607e992592135658ada1
 SHA512:
-  metadata.gz: a3ab34fbd35187ac36a8442076cb6cf9cd0afc01a0b870074e0d4308c650996ed4f36d810ef84b883bb23d80c176d0ce6a9112dce5cda7af2a5104f0ed49242d
-  data.tar.gz: e6ada66e602acf2b3edaf55ea8b6c248bf9354cb58c215daab2297962b3435aa8db98e799d50b4681893d27b3af2027faaeb65d0c2627f064522a9758ddc330e
+  metadata.gz: 8dedb952feff5a50e1f9f4e9250fd64c92d356c12cbada08777892b8897ef4c1c296c54aa6a1c1b1ed30d2eb4a0faab681e93bbc7fe72b824212c5619a314c35
+  data.tar.gz: af5ed4def4c983b362ae315fd81f4192d0bf23bf4fd82ef36c1f913d9a33c4e79dc3c04b1f8e695cd2eb5819d338dcfba2565bf233a45c3af7bf7a7784cea6eb

data/LICENSE

@@ -3,7 +3,7 @@ License:
 The MIT License (MIT)
 http://opensource.org/licenses/MIT
 
-Copyright (c) 2014 - 2025 APIMATIC Limited
+Copyright (c) 2014 - 2026 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

data/README.md

@@ -38,16 +38,51 @@ Go to the Shell Developer Portal: [https://developer.shell.com](https://develope
 Install the gem from the command line:
 
 ```bash
-gem install data-and-reporting-sdk -v 2.0.0
+gem install data-and-reporting-sdk -v 3.0.0
 ```
 
 Or add the gem to your Gemfile and run `bundle`:
 
 ```ruby
-gem 'data-and-reporting-sdk', '2.0.0'
+gem 'data-and-reporting-sdk', '3.0.0'
 ```
 
-For additional gem details, see the [RubyGems page for the data-and-reporting-sdk gem](https://rubygems.org/gems/data-and-reporting-sdk/versions/2.0.0).
+For additional gem details, see the [RubyGems page for the data-and-reporting-sdk gem](https://rubygems.org/gems/data-and-reporting-sdk/versions/3.0.0).
+
+## IRB Console Usage
+
+You can explore the SDK interactively using IRB in two ways
+
+### 1. Use IRB with Installed Gem
+
+Open your system terminal (Command Prompt, Git Bash or macOS Terminal) and type the following command to start the irb console.
+
+```bash
+irb
+```
+
+Now you can load the SDK in the IRB
+
+```ruby
+require 'shell_data_reporting_ap_is'
+include ShellDataReportingApIs
+```
+
+### 2. Use IRB within SDK
+
+Open your system terminal (Command Prompt, Git Bash or macOS Terminal) and navigate to the root folder of SDK.
+
+```
+cd path/to/shell_data_reporting_ap_is
+```
+
+Now you can start the preconfigured irb console by running the following command
+
+```bash
+ruby bin/console
+```
+
+**_Note:_** This automatically loads the SDK from lib/
 
 ## Test the SDK
 
@@ -59,13 +94,13 @@ rake
 
 ## Initialize the API Client
 
-**_Note:_** Documentation for the client can be found [here.](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/client.md)
+**_Note:_** Documentation for the client can be found [here.](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/client.md)
 
 The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| environment | `Environment` | The API environment. <br> **Default: `Environment.SIT`** |
+| environment | [`Environment`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/README.md#environments) | The API environment. <br> **Default: `Environment.SIT`** |
 | connection | `Faraday::Connection` | The Faraday connection object passed by the SDK user for making requests |
 | adapter | `Faraday::Adapter` | The Faraday adapter object passed by the SDK user for performing http requests |
 | timeout | `Float` | The value to use for connection timeout. <br> **Default: 60** |
@@ -75,11 +110,13 @@ The following parameters are configurable for the API Client:
 | retry_statuses | `Array` | A list of HTTP statuses to retry. <br> **Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]** |
 | retry_methods | `Array` | A list of HTTP methods to retry. <br> **Default: %i[get put]** |
 | http_callback | `HttpCallBack` | The Http CallBack allows defining callables for pre and post API calls. |
-| proxy_settings | [`ProxySettings`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/proxy-settings.md) | Optional proxy configuration to route HTTP requests through a proxy server. |
-| client_credentials_auth_credentials | [`ClientCredentialsAuthCredentials`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/auth/oauth-2-client-credentials-grant.md) | The credential object for OAuth 2 Client Credentials Grant |
+| proxy_settings | [`ProxySettings`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/proxy-settings.md) | Optional proxy configuration to route HTTP requests through a proxy server. |
+| client_credentials_auth_credentials | [`ClientCredentialsAuthCredentials`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/auth/oauth-2-client-credentials-grant.md) | The credential object for OAuth 2 Client Credentials Grant |
 
 The API client can be initialized as follows:
 
+### Code-Based Client Initialization
+
 ```ruby
 require 'shell_data_reporting_ap_is'
 include ShellDataReportingApIs
@@ -93,6 +130,18 @@ client = Client.new(
 )
 ```
 
+### Environment-Based Client Initialization
+
+```ruby
+require 'shell_data_reporting_ap_is'
+include ShellDataReportingApIs
+
+# Create client from environment
+client = Client.from_env
+```
+
+See the [`Environment-Based Client Initialization`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/environment-based-client-initialization.md) section for details.
+
 ## Environments
 
 The SDK can be configured to use a different environment for making API calls. Available environments are:
@@ -102,33 +151,34 @@ The SDK can be configured to use a different environment for making API calls. A
 | Name | Description |
 |  --- | --- |
 | SIT | **Default** |
-| Production | - |
+| PRODUCTION | - |
 
 ## Authorization
 
 This API uses the following authentication schemes.
 
-* [`BearerToken (OAuth 2 Client Credentials Grant)`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/auth/oauth-2-client-credentials-grant.md)
+* [`BearerToken (OAuth 2 Client Credentials Grant)`](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/auth/oauth-2-client-credentials-grant.md)
 
 ## List of APIs
 
-* [Customer](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/controllers/customer.md)
-* [Transaction](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/controllers/transaction.md)
-* [Invoice](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/controllers/invoice.md)
+* [Customer](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/controllers/customer.md)
+* [Transaction](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/controllers/transaction.md)
+* [Invoice](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/controllers/invoice.md)
 
 ## SDK Infrastructure
 
 ### Configuration
 
-* [ProxySettings](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/proxy-settings.md)
+* [ProxySettings](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/proxy-settings.md)
+* [Environment-Based Client Initialization](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/environment-based-client-initialization.md)
 
 ### HTTP
 
-* [HttpResponse](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/http-response.md)
-* [HttpRequest](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/http-request.md)
+* [HttpResponse](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/http-response.md)
+* [HttpRequest](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/http-request.md)
 
 ### Utilities
 
-* [ApiHelper](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/api-helper.md)
-* [DateTimeHelper](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/2.0.0/doc/date-time-helper.md)
+* [ApiHelper](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/api-helper.md)
+* [DateTimeHelper](https://www.github.com/sdks-io/data-and-reporting-ruby-sdk/tree/3.0.0/doc/date-time-helper.md)
 

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+# Load the lib folder into Ruby's load path
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+# Require the gem
+require 'shell_data_reporting_ap_is'
+
+puts 'ShellDataReportingApIs SDK loaded!'
+puts 'You can now create a client with: client = ShellDataReportingApIs::Client.new'
+puts 'Or use from_env: client = ShellDataReportingApIs::Client.from_env'
+
+# Start an interactive IRB session
+require 'irb'
+IRB.start

data/lib/shell_data_reporting_ap_is/client.rb

@@ -8,6 +8,10 @@ module ShellDataReportingApIs
   class Client
     include CoreLibrary
     attr_reader :config, :auth_managers
+
+    def user_agent_detail
+      config.user_agent_detail
+    end
 
     # Returns the configured authentication BearerToken instance.
     def bearer_token
@@ -43,8 +47,9 @@ module ShellDataReportingApIs
       max_retries: 0, retry_interval: 1, backoff_factor: 2,
       retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
       retry_methods: %i[get put], http_callback: nil, proxy_settings: nil,
-      environment: Environment::SIT, client_credentials_auth_credentials: nil,
-      config: nil
+      environment: Environment::SIT, o_auth_client_id: nil,
+      o_auth_client_secret: nil, o_auth_token: nil,
+      client_credentials_auth_credentials: nil, config: nil
     )
       @config = if config.nil?
                   Configuration.new(
@@ -54,6 +59,9 @@ module ShellDataReportingApIs
                     retry_statuses: retry_statuses,
                     retry_methods: retry_methods, http_callback: http_callback,
                     proxy_settings: proxy_settings, environment: environment,
+                    o_auth_client_id: o_auth_client_id,
+                    o_auth_client_secret: o_auth_client_secret,
+                    o_auth_token: o_auth_token,
                     client_credentials_auth_credentials: client_credentials_auth_credentials
                   )
                 else
@@ -79,5 +87,12 @@ module ShellDataReportingApIs
         http_client_config.client_credentials_auth_credentials, global_config
       )
     end
+
+    # Creates a client directly from environment variables.
+    def self.from_env(**overrides)
+      default_config = Configuration.build_default_config_from_env
+      new_config = default_config.clone_with(**overrides)
+      new(config: new_config)
+    end
   end
 end

data/lib/shell_data_reporting_ap_is/configuration.rb

@@ -10,6 +10,21 @@ module ShellDataReportingApIs
       SIT = 'SIT'.freeze,
       PRODUCTION = 'Production'.freeze
     ].freeze
+
+    # Converts a string or symbol into a valid Environment constant.
+    def self.from_value(value, default_value = SIT)
+      return default_value if value.nil?
+
+      str = value.to_s.strip.downcase
+      case str
+      when 'sit' then SIT
+      when 'production' then PRODUCTION
+
+      else
+        warn "[Environment] Unknown environment '#{value}', falling back to #{default_value} "
+        default_value
+      end
+    end
   end
 
   # An enum for API servers.
@@ -18,11 +33,38 @@ module ShellDataReportingApIs
       OAUTH_SERVER = 'OAuth Server'.freeze,
       SHELL = 'Shell'.freeze
     ].freeze
+
+    # Converts a string or symbol into a valid Server constant.
+    def self.from_value(value, default_value = OAUTH_SERVER)
+      return default_value if value.nil?
+
+      str = value.to_s.strip.downcase
+      case str
+      when 'oauth_server' then OAUTH_SERVER
+      when 'shell' then SHELL
+
+      else
+        warn "[Server] Unknown server '#{value}', falling back to #{default_value} "
+        default_value
+      end
+    end
   end
 
   # All configuration including auth info and base URI for the API access
   # are configured in this class.
   class Configuration < CoreLibrary::HttpClientConfiguration
+    def o_auth_client_id
+      @client_credentials_auth_credentials.o_auth_client_id
+    end
+
+    def o_auth_client_secret
+      @client_credentials_auth_credentials.o_auth_client_secret
+    end
+
+    def o_auth_token
+      @client_credentials_auth_credentials.o_auth_token
+    end
+
     # The attribute readers for properties.
     attr_reader :environment, :client_credentials_auth_credentials
 
@@ -35,7 +77,9 @@ module ShellDataReportingApIs
       max_retries: 0, retry_interval: 1, backoff_factor: 2,
       retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
       retry_methods: %i[get put], http_callback: nil, proxy_settings: nil,
-      environment: Environment::SIT, client_credentials_auth_credentials: nil
+      environment: Environment::SIT, o_auth_client_id: nil,
+      o_auth_client_secret: nil, o_auth_token: nil,
+      client_credentials_auth_credentials: nil
     )
       super connection: connection, adapter: adapter, timeout: timeout,
             max_retries: max_retries, retry_interval: retry_interval,
@@ -46,11 +90,24 @@ module ShellDataReportingApIs
       # Current API environment
       @environment = String(environment)
 
-      # The object holding OAuth 2 Client Credentials Grant credentials
-      @client_credentials_auth_credentials = client_credentials_auth_credentials
+      # OAuth 2 Client ID
+      @o_auth_client_id = o_auth_client_id
+
+      # OAuth 2 Client Secret
+      @o_auth_client_secret = o_auth_client_secret
+
+      # Object for storing information about the OAuth token
+      @o_auth_token = if o_auth_token.is_a? OAuthToken
+                        OAuthToken.from_hash o_auth_token.to_hash
+                      else
+                        o_auth_token
+                      end
 
       # Initializing OAuth 2 Client Credentials Grant credentials with the provided auth parameters
-      @client_credentials_auth_credentials = client_credentials_auth_credentials
+      @client_credentials_auth_credentials = create_auth_credentials_object(
+        o_auth_client_id, o_auth_client_secret, o_auth_token,
+        client_credentials_auth_credentials
+      )
 
       # The Http Client to use for making requests.
       set_http_client CoreLibrary::FaradayClient.new(self)
@@ -59,7 +116,8 @@ module ShellDataReportingApIs
     def clone_with(connection: nil, adapter: nil, timeout: nil,
                    max_retries: nil, retry_interval: nil, backoff_factor: nil,
                    retry_statuses: nil, retry_methods: nil, http_callback: nil,
-                   proxy_settings: nil, environment: nil,
+                   proxy_settings: nil, environment: nil, o_auth_client_id: nil,
+                   o_auth_client_secret: nil, o_auth_token: nil,
                    client_credentials_auth_credentials: nil)
       connection ||= self.connection
       adapter ||= self.adapter
@@ -72,7 +130,10 @@ module ShellDataReportingApIs
       http_callback ||= self.http_callback
       proxy_settings ||= self.proxy_settings
       environment ||= self.environment
-      client_credentials_auth_credentials ||= self.client_credentials_auth_credentials
+      client_credentials_auth_credentials = create_auth_credentials_object(
+        o_auth_client_id, o_auth_client_secret, o_auth_token,
+        client_credentials_auth_credentials || self.client_credentials_auth_credentials
+      )
 
       Configuration.new(
         connection: connection, adapter: adapter, timeout: timeout,
@@ -84,6 +145,30 @@ module ShellDataReportingApIs
       )
     end
 
+    def create_auth_credentials_object(o_auth_client_id, o_auth_client_secret,
+                                       o_auth_token,
+                                       client_credentials_auth_credentials)
+      return client_credentials_auth_credentials if o_auth_client_id.nil? &&
+                                                    o_auth_client_secret.nil? &&
+                                                    o_auth_token.nil?
+
+      warn('The \'o_auth_client_id\', \'o_auth_client_secret\', \'o_auth_token'\
+           '\' params are deprecated. Use \'client_credentials_auth_credential'\
+           's\' param instead.')
+
+      unless client_credentials_auth_credentials.nil?
+        return client_credentials_auth_credentials.clone_with(
+          o_auth_client_id: o_auth_client_id,
+          o_auth_client_secret: o_auth_client_secret,
+          o_auth_token: o_auth_token
+        )
+      end
+
+      ClientCredentialsAuthCredentials.new(
+        o_auth_client_id: o_auth_client_id,
+        o_auth_client_secret: o_auth_client_secret, o_auth_token: o_auth_token
+      )
+    end
 
     # All the environments the SDK can run in.
     ENVIRONMENTS = {
@@ -104,5 +189,46 @@ module ShellDataReportingApIs
     def get_base_uri(server = Server::SHELL)
       ENVIRONMENTS[environment][server].clone
     end
+
+    # Builds a Configuration instance using environment variables.
+    def self.build_default_config_from_env
+      # === Core environment ===
+      environment = Environment.from_value(ENV.fetch('ENVIRONMENT', 'sit'))
+      timeout = (ENV['TIMEOUT'] || 60).to_f
+      max_retries = (ENV['MAX_RETRIES'] || 0).to_i
+      retry_interval = (ENV['RETRY_INTERVAL'] || 1).to_f
+      backoff_factor = (ENV['BACKOFF_FACTOR'] || 2).to_f
+      retry_statuses = ENV.fetch('RETRY_STATUSES',
+                                 '[408, 413, 429, 500, 502, 503, 504, 521, 522, 524]').gsub(/[\[\]]/, '')
+                                          .split(',')
+                                          .map(&:strip)
+                                          .map do |item|
+                                            item.match?(/\A\d+\z/) ? item.to_i : item.downcase
+                                          end
+      retry_methods = ENV.fetch('RETRY_METHODS', '%i[get put]').gsub(/[\[\]]/, '')
+                                          .split(',')
+                                          .map(&:strip)
+                                          .map do |item|
+                                            item.match?(/\A\d+\z/) ? item.to_i : item.downcase
+                                          end
+
+      # === Authentication credentials ===
+      client_credentials_auth_credentials = ClientCredentialsAuthCredentials.from_env
+
+      # === Proxy settings ===
+      proxy_settings = ProxySettings.from_env
+
+      Configuration.new(
+        environment: environment,
+        timeout: timeout,
+        max_retries: max_retries,
+        retry_interval: retry_interval,
+        backoff_factor: backoff_factor,
+        retry_statuses: retry_statuses,
+        retry_methods: retry_methods,
+        client_credentials_auth_credentials: client_credentials_auth_credentials,
+        proxy_settings: proxy_settings
+      )
+    end
   end
 end