ibm_appconfiguration_ruby_sdk 0.1.0.pre.rc.0 → 0.1.0.pre.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1539bbf23de03af81f99e3be2c4e76e108e28979fc35b67cf9f65c8a485f1001
-  data.tar.gz: 3fcd5d046f1eb0585b514160d9b8313c9c05fb3909fab6551bdfd0af184eeba4
+  metadata.gz: d0d47f7822d5632c7775640cab20fb93c102b2c87f95ad8ac8d9a727ab6095b2
+  data.tar.gz: 64a9b3fabe1ff624452c0091304840e7bafa30b3322d47b2415334265ea4a2ce
 SHA512:
-  metadata.gz: 15f0f0389d53fd30f95e0be5a68743b35f68f2702633e8b7e0fa0aa1e403ec93283ace4e54b57815a34ddf180f7d55031977ba049bda36be946aabdd431466e5
-  data.tar.gz: c69ea5eb9f37de2b1369ade29206c5b5774085373fd7879b67383eacfe2c2fbd1206ce6467cb9034bd027968851b792118248ac728d63a69775ab024054c9e45
+  metadata.gz: 768acdd48dd6f827b6c9e8d38e4af4231117425e94fa278dbc7380d2be5779652939575a0d3a82a599e9ef922ee3423a598cd21be842cf7bb145d72ef8a9a4d2
+  data.tar.gz: 112afe2227835c6dc7a67ae2f0f1a80f187d840e48ee9a8c69c29477cb6b609ba2f48fed3991030befd9302480f105819599be6a1f2589cec136901bdff273c1

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## CHANGELOG
 
+## [0.1.0-rc.1] - 2026-08-24
+
+- `init` and `set_context` postional arguments changed to  keyword.
+- classes namespaced under `IbmAppconfigurationRubySdk` module.
+- replaced `puts` logging with structured stdlib `::Logger`.
+- improved error handling.
+- folder re-structure.
+- retries related fixes.
+- added test suite.
+- todos completed.
+
 ## [0.1.0-rc.0] - 2026-06-16
 
 - Initial release

data/README.md

@@ -26,13 +26,13 @@ the cloud to activate or deactivate features in your application or environment,
 Installation is done using the `gem install` command or by adding it to your Gemfile.
 
 ```bash
-gem install ibm_appconfiguration_ruby_sdk
+gem install ibm_appconfiguration_ruby_sdk --pre
 ```
 
 Or add this line to your application's Gemfile:
 
 ```ruby
-gem 'ibm_appconfiguration_ruby_sdk'
+gem "ibm_appconfiguration_ruby_sdk", "0.1.0.pre.rc.1"
 ```
 
 And then execute:
@@ -46,7 +46,7 @@ bundle install
 To import the module:
 
 ```ruby
-require 'ibm_appconfiguration_ruby_sdk'
+require "ibm_appconfiguration_ruby_sdk"
 ```
 
 ## Usage
@@ -54,53 +54,61 @@ require 'ibm_appconfiguration_ruby_sdk'
 Initialize the SDK to connect with your App Configuration service instance.
 
 ```ruby
-require 'ibm_appconfiguration_ruby_sdk'
+require "ibm_appconfiguration_ruby_sdk"
+
+region         = "us-south"
+guid           = "<guid>"
+apikey         = "<apikey>"
+collection_id  = "airlines-webapp"
+environment_id = "dev"
+
+# (Optional) SDK-wide options — call before .instance
+IbmAppconfigurationRubySdk::AppConfiguration.configure do |config|
+  config.debug                = false  # set true for verbose SDK logging
+  config.use_private_endpoint = false  # set true to use IBM private network
+end
 
 # Get the singleton instance
-app_config_client = IbmAppconfigurationRubySdk::AppConfiguration.instance
-
-region = 'us-south'
-guid = '<guid>'
-apikey = '<apikey>'
-collection_id = 'airlines-webapp'
-environment_id = 'dev'
+client = IbmAppconfigurationRubySdk::AppConfiguration.instance
 
-# Enable debug logging (optional)
-app_config_client.set_debug(true)
+# Initialize the SDK — keyword arguments are required
+client.init(region: region, guid: guid, apikey: apikey)
 
-# Initialize the SDK
-app_config_client.init(region, guid, apikey)
+# Register a listener before set_context so it fires on the very first config fetch
+client.register_configuration_update_listener do
+  # called on every configuration refresh (initial load + live updates)
+end
 
 # Set context
-app_config_client.set_context(collection_id, environment_id)
+client.set_context(collection_id, environment_id)
 ```
 
 > :warning: It is expected that initialization to be done **only once**.
 
-After the SDK is initialized successfully, the feature flags & properties can be retrieved using the `app_config_client` as shown in the below code snippet.
+After the SDK is initialized successfully, the feature flags & properties can be retrieved using the `client` as shown in the below code snippet.
 
 <details><summary>Expand to view the example snippet</summary>
 
 ```ruby
 # Get feature
-feature = app_config_client.get_feature('online-check-in')
+feature = client.get_feature("online-check-in")
 if feature
   result = feature.get_current_value(entity_id, entity_attributes)
-  puts result
+  puts result.value
 end
 
 # Get property
-property = app_config_client.get_property('check-in-charges')
+property = client.get_property("check-in-charges")
 if property
   result = property.get_current_value(entity_id, entity_attributes)
-  puts result
+  puts result.value
 end
 ```
 </details>
 
 where,
-- **region**: Region name where the App Configuration service instance is created. 
-See list of supported locations [here](https://cloud.ibm.com/catalog/services/app-configuration). Eg:- `us-south`, `au-syd`, `eu-gb`, `us-east`, `eu-de`, `ca-tor`, `jp-tok`, `jp-osa` etc.
+- **region**: Region name where the App Configuration service instance is created.
+  See list of supported locations [here](https://cloud.ibm.com/catalog/services/app-configuration). Eg:- `us-south`, `au-syd`, `eu-gb`, `us-east`, `eu-de`, `ca-tor`, `jp-tok`, `jp-osa` etc.
 - **guid**: Instance Id of the App Configuration service. Obtain it from the service credentials section of the App
   Configuration dashboard.
 - **apikey**: ApiKey of the App Configuration service. Obtain it from the service credentials section of the App
@@ -110,22 +118,30 @@ See list of supported locations [here](https://cloud.ibm.com/catalog/services/ap
 
 ### Connect using private network connection (optional)
 
-Set the SDK to connect to App Configuration service by using a private endpoint that is accessible only through the IBM Cloud private network.
+Set the SDK to connect to App Configuration service by using a private endpoint that is accessible only through the IBM Cloud private network. This must be configured before calling `init`.
+
+Via the `configure` block (preferred):
 
 ```ruby
-app_config_client.use_private_endpoint(true)
+IbmAppconfigurationRubySdk::AppConfiguration.configure do |config|
+  config.use_private_endpoint = true
+end
 ```
 
-This must be done before calling the `init` method on the SDK.
+Or directly on the client instance (must be called before `init`):
+
+```ruby
+client.use_private_endpoint(true)
+```
 
 ### (Optional)
 
 In order for your application and SDK to continue its operations even during the unlikely scenario of App Configuration service across your application restarts, you can configure the SDK to work using a persistent cache. The SDK uses the persistent cache to store the App Configuration data that will be available across your application restarts.
 
 ```ruby
-app_config_client.set_context(collection_id, environment_id, {
-  persistent_cache_directory: '/var/lib/docker/volumes/'
-})
+client.set_context(collection_id, environment_id,
+  persistent_cache_directory: "/var/lib/docker/volumes/"
+)
 ```
 
 * **persistent_cache_directory**: Absolute path to a directory which has read & write permission for the user. The SDK will create a file - `appconfiguration.json` in the specified directory, and it will be used as the persistent cache to store the App Configuration service information.
@@ -139,10 +155,10 @@ Please ensure that the cache file is not lost or deleted in any case. For exampl
 The SDK is also designed to serve configurations, perform feature flag & property evaluations without being connected to App Configuration service.
 
 ```ruby
-app_config_client.set_context(collection_id, environment_id, {
-  bootstrap_file: 'saflights/flights.json',
+client.set_context(collection_id, environment_id,
+  bootstrap_file: "saflights/flights.json",
   live_config_update_enabled: false
-})
+)
 ```
 
 This usecase will throw error if given `bootstrap_file` is not found or if unable to parse the json coming from the bootstrap file.
@@ -153,13 +169,13 @@ This usecase will throw error if given `bootstrap_file` is not found or if unabl
 ## Get single feature
 
 ```ruby
-feature = app_config_client.get_feature('online-check-in') # feature can be nil in case of an invalid feature id
+feature = client.get_feature("online-check-in") # feature can be nil in case of an invalid feature id
 
 if feature
-  puts "Feature Name: #{feature.get_feature_name}"
-  puts "Feature Id: #{feature.get_feature_id}"
-  puts "Feature Type: #{feature.get_feature_data_type}"
-  if feature.is_enabled?
+  puts "Feature Name: #{feature.name}"
+  puts "Feature Id: #{feature.feature_id}"
+  puts "Feature Type: #{feature.type}"
+  if feature.enabled?
     # feature flag is enabled
   else
     # feature flag is disabled
@@ -170,100 +186,87 @@ end
 ## Get all features
 
 ```ruby
-features = app_config_client.get_features
-feature = features['online-check-in']
+features = client.get_features
+feature = features["online-check-in"]
 
 if feature
-  puts "Feature Name: #{feature.get_feature_name}"
-  puts "Feature Id: #{feature.get_feature_id}"
-  puts "Feature Type: #{feature.get_feature_data_type}"
-  puts "Is feature enabled? #{feature.is_enabled?}"
+  puts "Feature Name: #{feature.name}"
+  puts "Feature Id: #{feature.feature_id}"
+  puts "Feature Type: #{feature.type}"
+  puts "Is feature enabled? #{feature.enabled?}"
 end
 ```
 
 ## Evaluate a feature
 
-Use the `feature.get_current_value(entity_id, entity_attributes)` method to evaluate the value of the feature flag. This method returns a Hash containing evaluated value, feature flag enabled status & evaluation details.
+Use the `feature.get_current_value(entity_id, entity_attributes)` method to evaluate the value of the feature flag. This method returns an `EvaluationResult` struct containing the evaluated value, feature flag enabled status, and evaluation details.
 
 ```ruby
-entity_id = 'john_doe'
+entity_id = "john_doe"
 entity_attributes = {
-  city: 'Bangalore',
-  country: 'India'
+  city: "Bangalore",
+  country: "India"
 }
 
 result = feature.get_current_value(entity_id, entity_attributes)
-puts result[:value] # Evaluated value of the feature flag. The type of evaluated value will match the type of feature flag (Boolean, String, Numeric).
-puts result[:is_enabled] # enabled status.
-puts result[:details] # a Hash containing detailed information of the evaluation. See below
-
-# the `result[:details]` will have the following
-puts result[:details][:value_type] # a string value. Example: DISABLED_VALUE
-puts result[:details][:reason] # a string value. Example: Disabled value of the feature flag since the feature flag is disabled.
-puts result[:details][:segment_name] # (only if applicable, else it is nil) a string value containing the segment name for which the feature flag was evaluated.
-puts result[:details][:rollout_percentage_applied] # (only if applicable, else it is nil) a boolean value. True if the entity_id was part of the rollout percentage evaluation, false otherwise.
-puts result[:details][:error_type] # (only if applicable, else it is nil) contains the error message if any error occurred during the evaluation.
+puts result.value    # Evaluated value of the feature flag. The type matches the feature flag type (Boolean, String, Numeric).
+puts result.enabled  # enabled status (true/false).
+puts result.details  # an EvaluationDetails struct with detailed evaluation information. See below.
+
+# the `result.details` struct has the following fields:
+puts result.details.value_type                  # e.g. "DISABLED_VALUE"
+puts result.details.rollout_percentage_applied  # (only if applicable, else nil) Boolean
+puts result.details.segment_name               # (only if applicable, else nil) e.g. "premium-users"
+puts result.details.error_type                 # (only if applicable, else nil) error message if evaluation failed
 ```
 
 - **entity_id**: Id of the Entity. This will be a string identifier related to the Entity against which the feature is evaluated. For example, an entity might be an instance of an app that runs on a mobile device, a microservice that runs on the cloud, or a component of infrastructure that runs that microservice. For any entity to interact with App Configuration, it must provide a unique entity ID.
 - **entity_attributes**: A Hash consisting of the attribute name and their values that defines the specified entity. This is an optional parameter if the feature flag is not configured with any targeting definition. If the targeting is configured, then entity_attributes should be provided for the rule evaluation. An attribute is a parameter that is used to define a segment. The SDK uses the attribute values to determine if the specified entity satisfies the targeting rules, and returns the appropriate feature flag value.
 
-## Send custom metrics
-
-Record custom metrics for experiments using the track method. Calling track will queue the metric event, which will be sent in batches to the App Configuration servers.
-
-```ruby
-app_config_client.track(event_key, entity_id)
-```
-
-where
-- **event_key**: The event key for the metric associated with the running experiment. The event key in your metric and the event key in your code must match exactly.
-
 ## Get single property
 
 ```ruby
-property = app_config_client.get_property('check-in-charges') # property can be nil in case of an invalid property id
+property = client.get_property("check-in-charges") # property can be nil in case of an invalid property id
 
 if property
-  puts "Property Name: #{property.get_property_name}"
-  puts "Property Id: #{property.get_property_id}"
-  puts "Property Type: #{property.get_property_data_type}"
+  puts "Property Name: #{property.name}"
+  puts "Property Id: #{property.property_id}"
+  puts "Property Type: #{property.type}"
 end
 ```
 
 ## Get all properties
 
 ```ruby
-properties = app_config_client.get_properties
-property = properties['check-in-charges']
+properties = client.get_properties
+property = properties["check-in-charges"]
 
 if property
-  puts "Property Name: #{property.get_property_name}"
-  puts "Property Id: #{property.get_property_id}"
-  puts "Property Type: #{property.get_property_data_type}"
+  puts "Property Name: #{property.name}"
+  puts "Property Id: #{property.property_id}"
+  puts "Property Type: #{property.type}"
 end
 ```
 
 ## Evaluate a property
 
-Use the `property.get_current_value(entity_id, entity_attributes)` method to evaluate the value of the property. This method returns a Hash containing evaluated value & evaluation details.
+Use the `property.get_current_value(entity_id, entity_attributes)` method to evaluate the value of the property. This method returns an `EvaluationResult` struct containing the evaluated value and evaluation details.
 
 ```ruby
-entity_id = 'john_doe'
+entity_id = "john_doe"
 entity_attributes = {
-  city: 'Bangalore',
-  country: 'India'
+  city: "Bangalore",
+  country: "India"
 }
 
 result = property.get_current_value(entity_id, entity_attributes)
-puts result[:value] # Evaluated value of the property. The type of evaluated value will match the type of property (Boolean, String, Numeric).
-puts result[:details] # a Hash containing detailed information of the evaluation. See below
-
-# the `result[:details]` will have the following
-puts result[:details][:value_type] # a string value. Example: DEFAULT_VALUE
-puts result[:details][:reason] # a string value. Example: Default value of the property.
-puts result[:details][:segment_name] # (only if applicable, else it is nil) a string value containing the segment name for which the property was evaluated.
-puts result[:details][:error_type] # (only if applicable, else it is nil) contains the error message if any error occurred during the evaluation.
+puts result.value    # Evaluated value of the property. The type matches the property type (Boolean, String, Numeric).
+puts result.details  # an EvaluationDetails struct with detailed evaluation information. See below.
+
+# the `result.details` struct has the following fields:
+puts result.details.value_type   # e.g. "DEFAULT_VALUE"
+puts result.details.segment_name # (only if applicable, else nil) e.g. "premium-users"
+puts result.details.error_type   # (only if applicable, else nil) error message if evaluation failed
 ```
 
 - **entity_id**: Id of the Entity. This will be a string identifier related to the Entity against which the property is evaluated. For example, an entity might be an instance of an app that runs on a mobile device, a microservice that runs on the cloud, or a component of infrastructure that runs that microservice. For any entity to interact with App Configuration, it must provide a unique entity ID.
@@ -274,7 +277,7 @@ puts result[:details][:error_type] # (only if applicable, else it is nil) contai
 Explicit method for getting the secret references stored in App Configuration.
 
 ```ruby
-secret_property_object = app_config_client.get_secret(property_id, secrets_manager_service)
+secret_property_object = client.get_secret(property_id, secrets_manager_service)
 ```
 
 - **property_id**: property_id is the unique string identifier, using this we will be able to fetch the property which will provide the necessary metadata to fetch the secret.
@@ -287,10 +290,10 @@ Use the `secret_property_object.get_current_value(entity_id, entity_attributes)`
 Note that the output of this method call is different from `get_current_value` invoked using feature & property objects. This method returns the actual secret value of the evaluated secret reference. The response contains the secret data from the Secrets Manager.
 
 ```ruby
-entity_id = 'john_doe'
+entity_id = "john_doe"
 entity_attributes = {
-  city: 'Bangalore',
-  country: 'India'
+  city: "Bangalore",
+  country: "India"
 }
 
 begin
@@ -301,69 +304,54 @@ rescue StandardError => e
 end
 ```
 
-## How to access the secret data from a successful response
+## Fetching the client across other modules
 
-<details><summary>Full example:</summary>
+Once the SDK is initialized, the client can be obtained across other modules as shown below:
 
 ```ruby
-require 'ibm_appconfiguration_ruby_sdk'
-require 'ibm_secrets_manager_sdk'
-
-app_config_client = IbmAppconfigurationRubySdk::AppConfiguration.instance
-
-begin
-  app_config_client.init(region, guid, apikey)
-  app_config_client.set_context(collection_id, environment_id)
-rescue StandardError => e
-  puts "Failed to initialize app configuration sdk: #{e}"
-end
-
-# Initialize Secrets Manager client
-authenticator = IbmCloudSdkCore::Authenticators::IamAuthenticator.new(
-  apikey: '<SECRETS_MANAGER_APIKEY>'
-)
-
-secrets_manager_service = IbmCloudSecretsManagerApiV2::SecretsManagerV2.new(
-  authenticator: authenticator
-)
-secrets_manager_service.service_url = '<SECRETS_MANAGER_INSTANCE_URL>'
-
-begin
-  secret_property_object = app_config_client.get_secret(property_id, secrets_manager_service)
-  response = secret_property_object.get_current_value(entity_id, entity_attributes)
+# **other modules**
 
-  # For Arbitrary secret type
-  puts response.result['payload']
+require "ibm_appconfiguration_ruby_sdk"
 
-  # For username-password secret type
-  puts response.result['username']
-  puts response.result['password']
+client = IbmAppconfigurationRubySdk::AppConfiguration.instance
 
-  # For key-value secret type
-  puts response.result['data']['key1']
-  puts response.result['data']['key2']
-rescue StandardError => e
-  # handle the error
-  puts "Error: #{e}"
-end
+feature = client.get_feature("online-check-in")
+result  = feature.get_current_value(entity_id, entity_attributes)
+puts result.value
+puts result.enabled
 ```
-</details>
 
-## Fetching the app_config_client across other modules
+## Error handling
 
-Once the SDK is initialized, the app_config_client can be obtained across other modules as shown below:
+The SDK raises typed errors that you can rescue individually or collectively.
 
 ```ruby
-# **other modules**
-
-require 'ibm_appconfiguration_ruby_sdk'
+begin
+  client.init(region: region, guid: guid, apikey: apikey)
+  client.set_context(collection_id, environment_id)
+rescue IbmAppconfigurationRubySdk::AuthenticationError => e
+  # HTTP 401 — invalid or expired API key
+  warn "Authentication failed (HTTP #{e.http_status}): #{e.message}"
+rescue IbmAppconfigurationRubySdk::APIError => e
+  # Any other HTTP error from the service
+  warn "API error (HTTP #{e.http_status}): #{e.message}"
+rescue IbmAppconfigurationRubySdk::ConfigurationError => e
+  # SDK used incorrectly — e.g. missing init parameters
+  warn "SDK configuration error: #{e.message}"
+end
+```
 
-app_config_client = IbmAppconfigurationRubySdk::AppConfiguration.instance
+Error class hierarchy:
 
-feature = app_config_client.get_feature('online-check-in')
-enabled = feature.is_enabled?
-result = feature.get_current_value(entity_id, entity_attributes)
-```
+| Class | Trigger |
+| --- | --- |
+| `IbmAppconfigurationRubySdk::Error` | Base class — rescue this to catch all SDK errors |
+| `IbmAppconfigurationRubySdk::ConfigurationError` | Incorrect SDK usage (missing params, wrong call order) |
+| `IbmAppconfigurationRubySdk::APIError` | HTTP error from the service (carries `http_status` & `http_body`) |
+| `IbmAppconfigurationRubySdk::AuthenticationError` | HTTP 401 |
+| `IbmAppconfigurationRubySdk::RateLimitError` | HTTP 429 |
+| `IbmAppconfigurationRubySdk::InvalidRequestError` | HTTP 400 / 422 |
+| `IbmAppconfigurationRubySdk::ServerError` | HTTP 5xx |
 
 ## Supported Data types
 
@@ -373,13 +361,13 @@ format accordingly as shown in the below table.
 
 <details><summary>View Table</summary>
 
-| **Feature or Property value**                                                                          | **DataType** | **DataFormat** | **Type of data returned <br> by `get_current_value[:value]`** | **Example output**                                                   |
+| **Feature or Property value**                                                                          | **DataType** | **DataFormat** | **Type of data returned <br> by `result.value`**      | **Example output**                                                   |
 | ------------------------------------------------------------------------------------------------------ | ------------ | -------------- | ----------------------------------------------------- | -------------------------------------------------------------------- |
-| `true`                                                                                                 | BOOLEAN      | not applicable | `Boolean`                                                | `true`                                                               |
+| `true`                                                                                                 | BOOLEAN      | not applicable | `Boolean`                                             | `true`                                                               |
 | `25`                                                                                                   | NUMERIC      | not applicable | `Numeric`                                             | `25`                                                                 |
-| "a string text"                                                                                        | STRING       | TEXT           | `String`                                              | `"a string text"`                                                      |
-| <pre>{<br>  "firefox": {<br>    "name": "Firefox",<br>    "pref_url": "about:config"<br>  }<br>}</pre> | STRING       | JSON           | `Hash`                              | `{"firefox"=>{"name"=>"Firefox","pref_url"=>"about:config"}}` |
-| <pre>men:<br>  - John Smith<br>  - Bill Jones<br>women:<br>  - Mary Smith<br>  - Susan Williams</pre>  | STRING       | YAML           | `String`                              | `"men:\n  - John Smith\n  - Bill Jones\nwomen:\n  - Mary Smith\n  - Susan Williams"` |
+| "a string text"                                                                                        | STRING       | TEXT           | `String`                                              | `"a string text"`                                                    |
+| <pre>{<br>  "firefox": {<br>    "name": "Firefox",<br>    "pref_url": "about:config"<br>  }<br>}</pre> | STRING       | JSON           | `Hash`                                                | `{"firefox"=>{"name"=>"Firefox","pref_url"=>"about:config"}}` |
+| <pre>men:<br>  - John Smith<br>  - Bill Jones<br>women:<br>  - Mary Smith<br>  - Susan Williams</pre>  | STRING       | YAML           | `String`                                              | `"men:\n  - John Smith\n  - Bill Jones\nwomen:\n  - Mary Smith\n  - Susan Williams"` |
 
 For property of type secret reference, refer to readme section [evaluate-a-secret-property](#evaluate-a-secret-property)
 </details>
@@ -387,17 +375,17 @@ For property of type secret reference, refer to readme section [evaluate-a-secre
 <details><summary>Feature flag</summary>
 
 ```ruby
-feature = app_config_client.get_feature('json-feature')
-feature.get_feature_data_type # STRING
-feature.get_feature_data_format # JSON
+feature = client.get_feature("json-feature")
+feature.type        # STRING
+feature.data_format # JSON
 
 # Example (traversing the returned Hash)
 result = feature.get_current_value(entity_id, entity_attributes)
-puts result[:value]['key'] # prints the value of the key
+puts result.value["key"] # prints the value of the key
 
-feature = app_config_client.get_feature('yaml-feature')
-feature.get_feature_data_type # STRING
-feature.get_feature_data_format # YAML
+feature = client.get_feature("yaml-feature")
+feature.type        # STRING
+feature.data_format # YAML
 feature.get_current_value(entity_id, entity_attributes)
 ```
 </details>
@@ -405,31 +393,31 @@ feature.get_current_value(entity_id, entity_attributes)
 <details><summary>Property</summary>
 
 ```ruby
-property = app_config_client.get_property('json-property')
-property.get_property_data_type # STRING
-property.get_property_data_format # JSON
+property = client.get_property("json-property")
+property.type        # STRING
+property.data_format # JSON
 
 # Example (traversing the returned Hash)
 result = property.get_current_value(entity_id, entity_attributes)
-puts result[:value]['key'] # prints the value of the key
+puts result.value["key"] # prints the value of the key
 
-property = app_config_client.get_property('yaml-property')
-property.get_property_data_type # STRING
-property.get_property_data_format # YAML
+property = client.get_property("yaml-property")
+property.type        # STRING
+property.data_format # YAML
 property.get_current_value(entity_id, entity_attributes)
 ```
 </details>
 
 ## Set listener for feature and property data changes
 
-The SDK provides a callback mechanism to notify you in real-time when feature flag's or property's configuration changes. You can register a configuration update listener using the same app_config_client.
+The SDK provides a callback mechanism to notify you in real-time when feature flag's or property's configuration changes. Register the listener after `init` but before `set_context` so it fires on the very first configuration fetch.
 
 ```ruby
-app_config_client.register_configuration_update_listener do
+client.register_configuration_update_listener do
   # **add your code**
   # To find the effect of any configuration changes, you can call the feature or property related methods
 
-  # feature = app_config_client.get_feature('online-check-in')
+  # feature = client.get_feature("online-check-in")
   # new_result = feature.get_current_value(entity_id, entity_attributes)
 end
 ```
@@ -439,7 +427,13 @@ end
 Use this method to enable/disable the logging in SDK.
 
 ```ruby
-app_config_client.set_debug(true)
+# Via the configure block (call before .instance)
+IbmAppconfigurationRubySdk::AppConfiguration.configure do |config|
+  config.debug = true
+end
+
+# Or directly on the client instance
+client.set_debug(true)
 ```
 
 ## Examples
@@ -457,7 +451,7 @@ https://{region}.apprapp.cloud.ibm.com:443
 wss://{region}.apprapp.cloud.ibm.com:443
 ```
 
-If opted for private endpoint by setting `app_config_client.use_private_endpoint(true)` then the allowlist will be
+If opted for private endpoint by setting `config.use_private_endpoint = true` (or `client.use_private_endpoint(true)`) then the allowlist will be
 
 ```
 https://cloud.ibm.com:443
@@ -471,4 +465,4 @@ where `region` is the region where your App Configuration service instance is pr
 ## License
 
 This project is released under the Apache 2.0 license. The license's full text can be found
-in [LICENSE](https://github.com/IBM/appconfiguration-ruby-sdk/blob/master/LICENSE)
+in [LICENSE](https://github.com/IBM/appconfiguration-ruby-sdk/blob/master/LICENSE)