renamed 0.1.0.beta.2 → 0.1.0.beta.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77538a9c46e4722a2be7b056217e87e168464c54317be54c8139cbdf0d5f7a6e
-  data.tar.gz: 03b4a3515b130d8d8eed9b47f2d7a2c083c4c9e05388051432ca3748c90d4abe
+  metadata.gz: 31508e35ffefb256df91e86574f12f02184fb5bc5d22fed0f0616375aa9d93cc
+  data.tar.gz: b138aec5441a1ea62da85eadbe4fc140835142c5c129d72022bbaf20fd351c6e
 SHA512:
-  metadata.gz: 3e1cce89fe45835b1eff235248236cf7229a86cb0f10d79fedd758670a6e5a352476a518baf498fac4cad04e2c93af0be809fecbe9ccdcd386f2355e0c01c06c
-  data.tar.gz: 32ce22cb167093c9770cd6ff79aa3d96701bd3099ff060d445189877f534a0991ba1324e9b2d3d1803618c7e532a2f8a376018d76fdc07c0aec61791ade83611
+  metadata.gz: 17b2a9745e9af5ad31ed190406dbc74429b5a300cbb9f46a248b5bed44b0a1d1fd51372f200bc6a8a160babc379f35f129892aeb4a64302815d1a079bf22f0f7
+  data.tar.gz: e3ae05db5bd86e6d22a83ee90ce5a08e7eb48e8e4018cc8ef235f9211a9c2f4c2789a6591e1b4dbe9301a47e654eefb6ccc2cb7ba095292aaea361b542fffcdc

data/README.md

@@ -1,6 +1,6 @@
 # Renamed Ruby SDK
 
-Official Ruby SDK for the [renamed.to](https://renamed.to) API. Rename files intelligently using AI, split PDFs, and extract structured data from documents.
+Official Ruby SDK for the [renamed.to](https://www.renamed.to) API. Rename files intelligently using AI, split PDFs, and extract structured data from documents.
 
 ## Installation
 
@@ -36,6 +36,10 @@ puts result.suggested_filename  # => "2025-01-15_AcmeCorp_INV-12345.pdf"
 puts result.folder_path         # => "Invoices/2025/January"
 ```
 
+## Examples
+
+See runnable examples in the SDK repo: [examples/ruby](https://github.com/renamed-to/renamed-sdk/tree/main/examples/ruby) (`basic_usage.rb`).
+
 ## Features
 
 ### Rename Files
@@ -135,10 +139,35 @@ client = Renamed::Client.new(
   api_key: 'rt_your_api_key',
   base_url: 'https://www.renamed.to/api/v1',  # Default
   timeout: 30,                                  # Request timeout in seconds
-  max_retries: 2                                # Number of retries for failed requests
+  max_retries: 2,                               # Number of retries for failed requests
+  debug: true,                                  # Enable debug logging
+  logger: Logger.new($stderr)                   # Custom logger (optional)
 )
 ```
 
+## Debug Logging
+
+Enable debug logging to see HTTP request details for troubleshooting:
+
+```ruby
+client = Renamed::Client.new(api_key: 'rt_...', debug: true)
+
+# Output:
+# [Renamed] POST /rename -> 200 (234ms)
+# [Renamed] Upload: document.pdf (1.2 MB)
+```
+
+Use Ruby's standard `Logger` for custom logging:
+
+```ruby
+require 'logger'
+
+logger = Logger.new('renamed.log')
+logger.level = Logger::DEBUG
+
+client = Renamed::Client.new(api_key: 'rt_...', logger: logger)
+```
+
 ## Error Handling
 
 The SDK provides specific error classes for different error conditions:

data/lib/renamed/async_job.rb

@@ -48,6 +48,7 @@ module Renamed
       while attempts < @max_attempts
         current_status = status
 
+        log_job_status(current_status)
         yield current_status if block_given?
 
         if current_status.status == "completed" && current_status.result
@@ -64,5 +65,11 @@ module Renamed
 
       raise JobError.new("Job polling timeout exceeded")
     end
+
+    private
+
+    def log_job_status(job_status)
+      @client.send(:log_job_status, job_status.job_id, job_status.status, job_status.progress)
+    end
   end
 end

data/lib/renamed/client.rb

@@ -3,6 +3,8 @@
 require "faraday"
 require "faraday/multipart"
 require "json"
+require "logger"
+require "uri"
 
 require_relative "errors"
 require_relative "models"
@@ -31,13 +33,16 @@ module Renamed
     # @param base_url [String] Base URL for the API
     # @param timeout [Integer] Request timeout in seconds
     # @param max_retries [Integer] Maximum number of retries for failed requests
-    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+    # @param debug [Boolean] Enable debug logging to stderr
+    # @param logger [Logger, nil] Custom logger instance (overrides debug flag)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, debug: false, logger: nil)
       raise AuthenticationError, "API key is required" if api_key.nil? || api_key.empty?
 
       @api_key = api_key
       @base_url = base_url.chomp("/")
       @timeout = timeout
       @max_retries = max_retries
+      @logger = setup_logger(debug, logger)
 
       @connection = build_connection
     end
@@ -181,7 +186,9 @@ module Renamed
 
       while attempts <= @max_retries
         begin
+          start_time = monotonic_time
           response = @connection.send(method, url, options[:body], options[:headers])
+          log_request(method, path, response.status, start_time)
           return handle_response(response)
         rescue Faraday::ConnectionFailed => e
           last_error = NetworkError.new(e.message)
@@ -195,7 +202,11 @@ module Renamed
         end
 
         attempts += 1
-        sleep(2**attempts * 0.1) if attempts <= @max_retries
+        if attempts <= @max_retries
+          backoff_ms = (2**attempts * 100).to_i
+          log_retry(attempts, @max_retries, backoff_ms)
+          sleep(backoff_ms / 1000.0)
+        end
       end
 
       raise last_error || NetworkError.new
@@ -229,6 +240,8 @@ module Renamed
     def upload_file(path, file, additional_fields: {})
       filename, content, mime_type = prepare_file(file)
 
+      log_upload(filename, content.bytesize)
+
       payload = {}
       payload[:file] = Faraday::Multipart::FilePart.new(
         StringIO.new(content),
@@ -246,7 +259,9 @@ module Renamed
 
       while attempts <= @max_retries
         begin
+          start_time = monotonic_time
           response = @connection.post(url, payload)
+          log_request(:post, path, response.status, start_time)
           return handle_response(response)
         rescue Faraday::ConnectionFailed => e
           last_error = NetworkError.new(e.message)
@@ -259,7 +274,11 @@ module Renamed
         end
 
         attempts += 1
-        sleep(2**attempts * 0.1) if attempts <= @max_retries
+        if attempts <= @max_retries
+          backoff_ms = (2**attempts * 100).to_i
+          log_retry(attempts, @max_retries, backoff_ms)
+          sleep(backoff_ms / 1000.0)
+        end
       end
 
       raise last_error || NetworkError.new
@@ -286,5 +305,65 @@ module Renamed
       ext = File.extname(filename).downcase
       MIME_TYPES[ext] || "application/octet-stream"
     end
+
+    # Logging helpers
+
+    def setup_logger(debug, logger)
+      return logger if logger
+
+      return nil unless debug
+
+      new_logger = Logger.new($stderr)
+      new_logger.level = Logger::DEBUG
+      new_logger.formatter = proc { |_severity, _datetime, _progname, msg| "#{msg}\n" }
+      new_logger
+    end
+
+    def log_debug(message)
+      @logger&.debug(message)
+    end
+
+    def log_request(method, path, status, start_time)
+      return unless @logger
+
+      elapsed_ms = ((monotonic_time - start_time) * 1000).round
+      # Normalize path to just the path portion (not full URL)
+      display_path = path.start_with?("http") ? URI.parse(path).path : path
+      log_debug("[Renamed] #{method.to_s.upcase} #{display_path} -> #{status} (#{elapsed_ms}ms)")
+    end
+
+    def log_retry(attempt, max_retries, backoff_ms)
+      log_debug("[Renamed] Retry attempt #{attempt}/#{max_retries}, waiting #{backoff_ms}ms")
+    end
+
+    def log_upload(filename, size_bytes)
+      log_debug("[Renamed] Upload: #{filename} (#{format_size(size_bytes)})")
+    end
+
+    def log_job_status(job_id, status, progress = nil)
+      message = "[Renamed] Job #{job_id}: #{status}"
+      message += " (#{progress}%)" if progress
+      log_debug(message)
+    end
+
+    def format_size(bytes)
+      if bytes >= 1_000_000
+        format("%.1f MB", bytes / 1_000_000.0)
+      elsif bytes >= 1_000
+        format("%.1f KB", bytes / 1_000.0)
+      else
+        "#{bytes} B"
+      end
+    end
+
+    def mask_api_key(key)
+      return "***" if key.nil? || key.length < 7
+
+      "#{key[0, 3]}...#{key[-4, 4]}"
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
   end
 end

data/lib/renamed/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Renamed
-  VERSION = "0.1.0.beta.2"
+  VERSION = "0.1.0.beta.4"
 end

data/lib/renamed.rb

@@ -21,6 +21,6 @@ require_relative "renamed/client"
 #   user = client.get_user
 #   puts "Credits: #{user.credits}"
 #
-# @see https://renamed.to/docs API Documentation
+# @see https://www.renamed.to/docs API Documentation
 module Renamed
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: renamed
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta.2
+  version: 0.1.0.beta.4
 platform: ruby
 authors:
 - renamed.to
@@ -143,14 +143,14 @@ files:
 - lib/renamed/errors.rb
 - lib/renamed/models.rb
 - lib/renamed/version.rb
-homepage: https://renamed.to
+homepage: https://www.renamed.to
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://renamed.to
+  homepage_uri: https://www.renamed.to
   source_code_uri: https://github.com/renamed-to/renamed-sdk
   changelog_uri: https://github.com/renamed-to/renamed-sdk/blob/main/sdks/ruby/CHANGELOG.md
-  documentation_uri: https://renamed.to/docs
+  documentation_uri: https://www.renamed.to/docs
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []