easyship 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48a6c8c265dc7c60e8b1b749032f29632ba74b79df21192bc8e7c5a2a80aea26
-  data.tar.gz: e6e52aba415127500177c16db9e1e99c931fda0bcc5642e60e69dc973efae886
+  metadata.gz: 90edef7622104c80daa116acd3a8511e63939faa885ad87913a2749d554f75c6
+  data.tar.gz: a771f5e0d156e2aaf7a4dd8603116572d870903b3fb1d6ab5de1e638a55881eb
 SHA512:
-  metadata.gz: 821d88416be393652174144a6ae29161ee7c4b43cde9c478515653365f1d84b7c9e11fc7b7ea4e5bd75b932cac3b672d572eb173ba2fab2e01f9e30286edaf42
-  data.tar.gz: 16eba98f3e5de4334a8d182e96262da79eb3dcfc1d61709652fb315603971466a1fb42ed65dfe9ebae9f72c747892e7ca20a3c3a83075640af88a1989321d6a4
+  metadata.gz: fffafc0e173ec627975fc5acb4ead24044a3633ca66d19255e3fc6f1e1180d4ec733a1464327aa491f5a4710d7d5b802334d225912d203a8ad15c278e22eef4b
+  data.tar.gz: 2af5b4ef1969f9dc05595fda224688f0ec1787f2fe3ca516c6119dc4c6f052afc4cbafcf074d3d8a0451e5df16b1a0c957fa385990fe6243237d59f0935a8ad0

data/.rubocop.yml

@@ -14,4 +14,8 @@ RSpec/ExampleLength:
   Max: 10
 
 RSpec/NestedGroups:
-  Max: 5
+  Max: 5
+
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/integration/**/*_spec.rb'

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [v0.6.0](https://github.com/mmarusyk/easyship/tree/v0.6.0) - 2026-02-28
+
+### Added
+- Secure logging module with configurable logger support
+- `NullLogger` as default (quiet by default) to avoid log pollution
+- Abstract logging methods: `log_info`, `log_debug`, `log_warn`, `log_error`, `log_request`, `log_response`
+- Logger configuration option to allow custom loggers (Rails.logger, custom Logger, etc.)
+- Integration tests for logging functionality
+- Security-first logging: no API keys, headers, or request/response bodies logged
+
 ## [v0.5.1](https://github.com/mmarusyk/easyship/tree/v0.5.1) - 2026-01-24
 
 ### Fixed

data/CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE Instructions
+
+## Release Instruction
+
+### 1. Ensure you are on `main` and it is up-to-date
+
+```bash
+git checkout main
+git pull origin main
+```
+
+---
+
+### 2. Determine the next version
+
+Follow [Semantic Versioning](https://semver.org/):
+
+| Change type | Example bump |
+|---|---|
+| Bug fixes only | `0.5.1` → `0.5.2` |
+| New backward-compatible features | `0.5.1` → `0.6.0` |
+| Breaking changes | `0.5.1` → `1.0.0` |
+
+Current version is in `lib/easyship/version.rb`. Review the `[Unreleased]` section of `CHANGELOG.md` to decide the correct bump type.
+
+---
+
+### 3. Update the version constant
+
+Edit `lib/easyship/version.rb` and set the new version:
+
+```ruby
+module Easyship
+  VERSION = 'X.Y.Z'  # replace with the new version
+end
+```
+
+---
+
+### 4. Update `CHANGELOG.md`
+
+The changelog follows [Keep a Changelog](https://keepachangelog.com/) format.
+
+- Rename the `## [Unreleased]` section header to `## [vX.Y.Z](https://github.com/mmarusyk/easyship/tree/vX.Y.Z) - YYYY-MM-DD`
+  - Use today's date in `YYYY-MM-DD` format.
+- Add a new empty `## [Unreleased]` section at the top (above the new version section).
+
+**Before:**
+```markdown
+## [Unreleased]
+
+### Added
+- Some new feature
+```
+
+**After:**
+```markdown
+## [Unreleased]
+
+## [v0.6.0](https://github.com/mmarusyk/easyship/tree/v0.6.0) - 2026-02-28
+
+### Added
+- Some new feature
+```
+
+---
+
+### 5. Run bundle install and tests with linting
+
+```bash
+bundle install
+bundle exec rake
+```
+
+This runs both the test suite (`rspec`) and linter (`rubocop`). **Do not proceed if either fails.** Fix all issues before continuing.
+
+---
+
+### 6. Commit the release changes
+
+Stage only the version and changelog files:
+
+```bash
+git add lib/easyship/version.rb CHANGELOG.md Gemfile.lock
+git commit -m "Release vX.Y.Z"
+```
+
+The commit message must follow the pattern `Release vX.Y.Z` exactly (e.g. `Release v0.6.0`).
+
+---
+
+### 7. Push the commit to `main`
+
+```bash
+git push origin main
+```
+
+---
+
+### 8. Create and push the version tag
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Pushing a tag matching `v*` automatically triggers the `.github/workflows/release.yml` GitHub Actions workflow, which builds and publishes the gem to RubyGems.org using trusted publishing (no manual API key needed).
+
+---
+
+### 9. Verify the release
+
+- Check the [Actions tab](https://github.com/mmarusyk/easyship/actions) to confirm the `Release Gem` workflow completed successfully.
+- Confirm the new version appears on [RubyGems.org](https://rubygems.org/gems/easyship).
+
+---

data/README.md

@@ -58,7 +58,72 @@ Easyship.configure do |config|
 end
 ```
 
-Configuration supports the next keys: `url`, `api_key`, `per_page`, `requests_per_second`, `requests_per_minute`, `headers`.
+Configuration supports the next keys: `url`, `api_key`, `per_page`, `requests_per_second`, `requests_per_minute`, `headers`, `logger`.
+
+### Logging
+
+The gem includes secure, professional logging capabilities that are **quiet by default**. Logging is designed to be abstract and never exposes sensitive data like API keys, headers, or request/response bodies.
+
+**Default Behavior (Quiet & Secure):**
+```ruby
+# By default, logging is disabled (NullLogger)
+Easyship.configure do |config|
+  config.url = 'api_url'
+  config.api_key = 'your_easyship_api_key'
+  # No logging output - completely silent
+end
+```
+
+**Using Rails Logger:**
+```ruby
+# In config/initializers/easyship.rb
+Easyship.configure do |config|
+  config.url = 'api_url'
+  config.api_key = 'your_easyship_api_key'
+  config.logger = Rails.logger
+end
+```
+
+**Using Custom Logger:**
+```ruby
+require 'logger'
+
+custom_logger = Logger.new(STDOUT)
+custom_logger.level = Logger::INFO
+
+Easyship.configure do |config|
+  config.url = 'api_url'
+  config.api_key = 'your_easyship_api_key'
+  config.logger = custom_logger
+end
+```
+
+**Log File Output:**
+```ruby
+Easyship.configure do |config|
+  config.url = 'api_url'
+  config.api_key = 'your_easyship_api_key'
+  config.logger = Logger.new('log/easyship.log')
+end
+```
+
+**Example Log Output:**
+```
+[Easyship] GET /2023-01/account
+[Easyship] Response 200 (0.245s)
+[Easyship] POST /2023-01/shipments
+[Easyship] Response 201 (0.432s)
+[Easyship] Error: InvalidTokenError - Invalid API token | Context: {:method=>:get, :path=>"/2023-01/account"}
+```
+
+**Extensibility:**
+You can extend logger module for custom logging needs:
+- `log_info(logger, message)` - General info logging
+- `log_debug(logger, message)` - Debug logging
+- `log_warn(logger, message)` - Warning logging
+- `log_error(logger, error, context)` - Error with context
+- `log_request(logger, method, path)` - Request logging
+- `log_response(logger, status, duration)` - Response logging
 
 ### Making Requests
 `Easyship::Client` supports the next methods: `get`, `post`, `put`, `patch`, `delete`.

data/lib/easyship/client.rb

@@ -5,53 +5,71 @@ require 'faraday'
 require_relative 'middleware/error_handler_middleware'
 require_relative 'handlers/response_body_handler'
 require_relative 'pagination/cursor'
+require_relative 'logging/logger'
 
 module Easyship
   # Represents a client to interact with the Easyship API
   class Client
     include Singleton
+    include Easyship::Logging::Logger
 
     def initialize
       @url = Easyship.configuration.url
       @api_key = Easyship.configuration.api_key
+      @logger = Easyship.configuration.logger
     end
 
     def get(path, params = {}, headers: {}, &block)
       if block
         Easyship::Pagination::Cursor.new(self, path, params).all(&block)
       else
-        response = connection(headers).get(path, params)
-
-        handle_response(response)
+        execute_request(:get, path, params, headers) do |conn|
+          conn.get(path, params)
+        end
       end
     end
 
     def post(path, params = {}, headers: {})
-      response = connection(headers).post(path, params.to_json)
-
-      handle_response(response)
+      execute_request(:post, path, params, headers) do |conn|
+        conn.post(path, params.to_json)
+      end
     end
 
     def put(path, params = {}, headers: {})
-      response = connection(headers).put(path, params.to_json)
-
-      handle_response(response)
+      execute_request(:put, path, params, headers) do |conn|
+        conn.put(path, params.to_json)
+      end
     end
 
     def delete(path, params = {}, headers: {})
-      response = connection(headers).delete(path, params)
-
-      handle_response(response)
+      execute_request(:delete, path, params, headers) do |conn|
+        conn.delete(path, params)
+      end
     end
 
     def patch(path, params = {}, headers: {})
-      response = connection(headers).patch(path, params.to_json)
-
-      handle_response(response)
+      execute_request(:patch, path, params, headers) do |conn|
+        conn.patch(path, params.to_json)
+      end
     end
 
     private
 
+    def execute_request(method, path, _params, headers)
+      log_request(@logger, method, path)
+
+      start_time = Time.now
+      response = yield(connection(headers))
+      duration = Time.now - start_time
+
+      log_response(@logger, response.status, duration)
+
+      handle_response(response)
+    rescue StandardError => e
+      log_error(@logger, e, { method: method, path: path })
+      raise
+    end
+
     def connection(custom_headers = {})
       Faraday.new(url: @url) do |faraday|
         faraday.request :url_encoded

data/lib/easyship/configuration.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative 'logging/null_logger'
+
 module Easyship
   # Represents the configuration settings for the Easyship client.
   class Configuration
-    attr_accessor :url, :api_key, :per_page, :requests_per_second, :requests_per_minute, :headers
+    attr_accessor :url, :api_key, :per_page, :requests_per_second, :requests_per_minute, :headers, :logger
 
     def initialize
       @url = nil
@@ -12,6 +14,7 @@ module Easyship
       @requests_per_second = nil
       @requests_per_minute = nil
       @headers = {}
+      @logger = Easyship::Logging::NullLogger.new
     end
   end
 end

data/lib/easyship/logging/logger.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Easyship
+  module Logging
+    # This module provides logging methods that can be included in any class
+    # to add secure, standardized logging capabilities.
+    module Logger
+      def log_info(logger, message)
+        return unless logger
+
+        logger.info("[Easyship] #{message}")
+      end
+
+      def log_debug(logger, message)
+        return unless logger
+
+        logger.debug("[Easyship] #{message}")
+      end
+
+      def log_warn(logger, message)
+        return unless logger
+
+        logger.warn("[Easyship] #{message}")
+      end
+
+      def log_error(logger, error, context = {})
+        return unless logger
+
+        logger.error do
+          message = "[Easyship] Error: #{error.class} - #{error.message}"
+          message += " | Context: #{context}" if context.any?
+          message += "\n#{error.backtrace.join("\n")}" if error.backtrace
+          message
+        end
+      end
+
+      def log_request(logger, method, path)
+        return unless logger
+
+        logger.info("[Easyship] #{method.to_s.upcase} #{path}")
+      end
+
+      def log_response(logger, status, duration = nil)
+        return unless logger
+
+        level = response_log_level(status)
+        message = "[Easyship] Response #{status}"
+        message += " (#{format('%.3f', duration)}s)" if duration
+
+        logger.public_send(level, message)
+      end
+
+      private
+
+      def response_log_level(status)
+        return :warn if status.between?(400, 499)
+        return :error if status.between?(500, 599)
+        return :debug if status.between?(200, 299)
+
+        :info
+      end
+    end
+  end
+end

data/lib/easyship/logging/null_logger.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Easyship
+  module Logging
+    # Implements the standard Logger interface but performs no actual logging,
+    # making it safe to use as a default without any output or performance impact.
+    class NullLogger
+      def debug(_message = nil, &); end
+
+      def info(_message = nil, &); end
+
+      def warn(_message = nil, &); end
+
+      def error(_message = nil, &); end
+
+      def fatal(_message = nil, &); end
+
+      def unknown(_message = nil, &); end
+
+      def level=(_level); end
+
+      def level
+        ::Logger::UNKNOWN
+      end
+
+      def tagged(*_tags)
+        yield self if block_given?
+      end
+
+      def formatter=(_formatter); end
+
+      def formatter
+        nil
+      end
+    end
+  end
+end

data/lib/easyship/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Easyship
-  VERSION = '0.5.1'
+  VERSION = '0.6.0'
 end

data/lib/easyship.rb

@@ -2,6 +2,8 @@
 
 require_relative 'easyship/version'
 require_relative 'easyship/configuration'
+require_relative 'easyship/logging/null_logger'
+require_relative 'easyship/logging/logger'
 require_relative 'easyship/client'
 require_relative 'easyship/rate_limiting/rate_limiter'
 require_relative 'easyship/rate_limiting/window_rate_limiter'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: easyship
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Michael Marusyk
 bindir: exe
 cert_chain: []
-date: 2026-01-24 00:00:00.000000000 Z
+date: 2026-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -35,6 +35,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTORS.md
 - LICENSE.txt
@@ -54,6 +55,8 @@ files:
 - lib/easyship/errors/server_error.rb
 - lib/easyship/errors/unprocessable_content_error.rb
 - lib/easyship/handlers/response_body_handler.rb
+- lib/easyship/logging/logger.rb
+- lib/easyship/logging/null_logger.rb
 - lib/easyship/middleware/error_handler_middleware.rb
 - lib/easyship/pagination/cursor.rb
 - lib/easyship/rate_limiting/rate_limiter.rb