lightrate-client 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c63b6519eeb427af97e5de527bc710be417a302dedde208d0915b259c9ef1ed7
+  data.tar.gz: 62a4447c9e7f57358552a447aa06553a51a40a116c09d376e9a3e6d4c18ddcfe
+SHA512:
+  metadata.gz: 47024b5debeb8cbfef45d0cbdb7263bd43a7d4959acf37bf506541a12af07149dc27869775e73468793baddb0dc60d73ffa50fc4868f14fc99098b949ef42189
+  data.tar.gz: d89180c3cb9399316b73903ec63078d9bd02a522a157781916f09c154658a82024ef87064752996a77144f7ac370e97176975bf409817c7960a5820e918a003f

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.7
+  Exclude:
+    - 'spec/fixtures/**/*'
+    - 'vendor/**/*'
+
+Layout/LineLength:
+  Max: 120
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/AbcSize:
+  Max: 20

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in lightrate-client.gemspec
+gemspec
+
+group :development, :test do
+  gem "pry", "~> 0.14"
+  gem "pry-byebug", "~> 3.10"
+end

data/Gemfile.lock

@@ -0,0 +1,133 @@
+PATH
+  remote: .
+  specs:
+    lightrate-client (1.0.0)
+      faraday (~> 2.0)
+      faraday-retry (~> 2.0)
+      json (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (3.2.3)
+    byebug (12.0.0)
+    coderay (1.1.3)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    faraday (2.13.4)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    hashdiff (1.2.1)
+    json (2.15.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    method_source (1.1.0)
+    net-http (0.6.0)
+      uri
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.5.1)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.11.0)
+      byebug (~> 12.0)
+      pry (>= 0.13, < 0.16)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.81.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.27.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.3)
+    vcr (6.3.1)
+      base64
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  ruby
+  x86_64-darwin-22
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  lightrate-client!
+  pry (~> 0.14)
+  pry-byebug (~> 3.10)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+  rubocop-rspec (~> 2.0)
+  simplecov (~> 0.21)
+  vcr (~> 6.0)
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.5.21

data/README.md

@@ -0,0 +1,289 @@
+# Lightrate Client Ruby
+
+A Ruby gem for interacting with the Lightrate token management API, providing easy-to-use methods for consuming tokens.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lightrate-client'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install lightrate-client
+```
+
+## Usage
+
+### Configuration
+
+Configure the client with your API credentials:
+
+```ruby
+require 'lightrate_client'
+
+LightrateClient.configure do |config|
+  config.api_key = 'your_api_key'
+  config.application_id = 'your_application_id' # required
+  config.timeout = 30 # optional, defaults to 30 seconds
+  config.retry_attempts = 3 # optional, defaults to 3
+  config.logger = Logger.new(STDOUT) # optional, for request logging
+end
+```
+
+### Basic Usage
+
+```ruby
+# Simple usage - pass your API key and application ID
+client = LightrateClient::Client.new('your_api_key', 'your_application_id')
+
+# Or use the convenience method
+client = LightrateClient.new_client('your_api_key', 'your_application_id')
+
+# With additional options
+client = LightrateClient::Client.new('your_api_key', 'your_application_id',
+  timeout: 60
+)
+
+# Or configure globally and use the default client
+LightrateClient.configure do |config|
+  config.api_key = 'your_api_key'
+  config.application_id = 'your_application_id'
+end
+client = LightrateClient.client
+```
+
+### Token Consumption Methods
+
+The Lightrate Client provides two methods for consuming tokens, each with different performance characteristics:
+
+#### 🚀 Recommended: Local Token Buckets (`consume_local_bucket_token`)
+
+**Use this method for high-frequency token consumption.** It maintains local token buckets that are refilled in batches from the API, dramatically reducing the number of HTTP requests.
+
+```ruby
+# Configure client with default bucket size
+client = LightrateClient::Client.new(
+  'your_api_key', 
+  'your_application_id',
+  default_local_bucket_size: 20  # Default bucket size for all operations
+)
+
+# Consume tokens using local buckets (fast, reduces API calls)
+response = client.consume_local_bucket_token(
+  operation: 'send_email',
+  user_identifier: 'user123'
+)
+
+puts "Success: #{response.success}"
+puts "Used local token: #{response.used_local_token}"
+puts "Bucket status: #{response.bucket_status}"
+
+# Or consume by path
+response = client.consume_local_bucket_token(
+  path: '/api/v1/emails/send',
+  http_method: 'POST',
+  user_identifier: 'user123'
+)
+```
+
+**Benefits of Local Buckets:**
+- ⚡ **Fast**: Most token consumption happens locally without HTTP requests
+- 🔄 **Efficient**: Batches token requests to reduce API calls by 95%+
+- 🛡️ **Resilient**: Continues working even with temporary API outages
+- 🎯 **Configurable**: Customizable bucket sizes for your application needs
+
+#### 🌐 Direct API Calls (`consume_tokens`)
+
+**Use this method for occasional token consumption or when you need immediate API feedback.**
+
+```ruby
+# Direct API call - makes HTTP request every time
+response = client.consume_tokens(
+  operation: 'send_email',
+  user_identifier: 'user123',
+  tokens_requested: 1
+)
+
+puts "Tokens consumed: #{response.tokens_consumed}"
+puts "Tokens remaining: #{response.tokens_remaining}"
+puts "Throttles: #{response.throttles}"
+puts "Rule: #{response.rule.name} (ID: #{response.rule.id})"
+```
+
+**When to use Direct API Calls:**
+- 🔍 **Debugging**: When you need immediate API feedback
+- 📊 **Monitoring**: For applications that rarely consume tokens
+- 🎛️ **Control**: When you need precise control over token requests
+- 🔄 **Legacy**: For compatibility with existing code
+
+### Method Comparison
+
+| Feature | Local Buckets | Direct API |
+|---------|---------------|------------|
+| **Speed** | ⚡ Very Fast | 🐌 Network dependent |
+| **API Calls** | 📉 Minimal (95%+ reduction) | 📈 Every request |
+| **Resilience** | 🛡️ High (works offline briefly) | 🔗 Requires network |
+| **Feedback** | 📊 Bucket status only | 📋 Full API response |
+| **Best For** | High-frequency usage | Occasional usage |
+
+### Performance Benefits
+
+**Local Token Buckets dramatically improve performance:**
+
+- **95%+ reduction in API calls** - Instead of making an HTTP request for every token consumption, tokens are fetched in batches
+- **Sub-millisecond response times** - Local token consumption is nearly instant
+- **Better reliability** - Continues working even during brief API outages
+- **Reduced bandwidth costs** - Fewer HTTP requests mean lower network usage
+
+**Example Performance Comparison:**
+```ruby
+# ❌ Slow: Direct API calls
+1000.times do
+  client.consume_tokens(operation: 'send_email', user_identifier: 'user123', tokens_requested: 1)
+  # Each call: ~100-200ms network latency
+end
+# Total: 1000 API calls, ~100-200 seconds
+
+# ✅ Fast: Local buckets
+1000.times do
+  client.consume_local_bucket_token(operation: 'send_email', user_identifier: 'user123')
+  # Each call: ~0.1ms local operation
+end
+# Total: ~1 API call, ~0.1 seconds
+```
+
+### When to Use Each Method
+
+**Use Local Buckets when:**
+- 🚀 Building high-performance applications
+- 📧 Sending bulk emails, SMS, or notifications
+- 🔄 Processing webhooks or background jobs
+- 📊 Handling user-facing requests that need fast response times
+- 🏭 Running production applications with high token usage
+
+**Use Direct API when:**
+- 🔍 Debugging or testing rate limiting
+- 📊 Building monitoring dashboards
+- 🎛️ Need immediate feedback on token consumption
+- 🔄 Migrating from existing implementations
+- 📱 Building low-frequency applications (fewer than 10 requests/minute)
+
+
+
+### Complete Example: High-Performance Token Consumption
+
+```ruby
+require 'lightrate_client'
+
+# Create a client with default bucket size
+client = LightrateClient::Client.new(
+  ENV['LIGHTRATE_API_KEY'] || 'your_api_key',
+  ENV['LIGHTRATE_APPLICATION_ID'] || 'your_application_id',
+  default_local_bucket_size: 50  # All operations use this bucket size
+)
+
+begin
+  # First call: Fetches 50 tokens from API and consumes 1 locally
+  response1 = client.consume_local_bucket_token(
+    operation: 'send_email',
+    user_identifier: 'user123'
+  )
+  
+  puts "First call - Success: #{response1.success}"
+  puts "Used local token: #{response1.used_local_token}"
+  puts "Bucket status: #{response1.bucket_status}"
+  
+  # Second call: Consumes from local bucket (no API call!)
+  response2 = client.consume_local_bucket_token(
+    operation: 'send_email',
+    user_identifier: 'user123'
+  )
+  
+  puts "Second call - Success: #{response2.success}"
+  puts "Used local token: #{response2.used_local_token}"
+  puts "Bucket status: #{response2.bucket_status}"
+  
+  # Example with path-based consumption
+  response3 = client.consume_local_bucket_token(
+    path: '/api/v1/emails/send',
+    http_method: 'POST',
+    user_identifier: 'user123'
+  )
+  
+  puts "Path-based call - Success: #{response3.success}"
+  puts "Bucket status: #{response3.bucket_status}"
+  
+  # Proceed with your operations...
+
+rescue LightrateClient::UnauthorizedError => e
+  puts "❌ Authentication failed: #{e.message}"
+rescue LightrateClient::TooManyRequestsError => e
+  puts "⚠️  Rate limited: #{e.message}"
+rescue LightrateClient::APIError => e
+  puts "❌ API Error (#{e.status_code}): #{e.message}"
+rescue LightrateClient::NetworkError => e
+  puts "❌ Network error: #{e.message}"
+end
+```
+
+### Advanced Configuration
+
+```ruby
+# For applications with very high token consumption
+client = LightrateClient::Client.new(
+  'your_api_key',
+  'your_application_id',
+  default_local_bucket_size: 500,  # Large default bucket for all operations
+  timeout: 60,                      # Longer timeout for large bucket requests
+  retry_attempts: 5,                # More retries for reliability
+  logger: Logger.new(STDOUT)        # Enable request logging
+)
+```
+
+## Error Handling
+
+The gem provides comprehensive error handling with specific exception types:
+
+```ruby
+begin
+  client.users
+rescue LightrateClient::UnauthorizedError => e
+  puts "Authentication failed: #{e.message}"
+rescue LightrateClient::NotFoundError => e
+  puts "Resource not found: #{e.message}"
+rescue LightrateClient::APIError => e
+  puts "API Error (#{e.status_code}): #{e.message}"
+rescue LightrateClient::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue LightrateClient::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lightbourne-technologies/lightrate-client-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/lightbourne-technologies/lightrate-client-ruby/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Lightrate Client Ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/lightbourne-technologies/lightrate-client-ruby/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+task default: :spec

data/examples/basic_usage.rb

@@ -0,0 +1,146 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'lightrate_client'
+
+# This example demonstrates the Lightrate Client with the new API response structure.
+# The consume_tokens API now returns:
+# - tokensRemaining: Number of tokens left in the bucket
+# - tokensConsumed: Number of tokens consumed in this request
+# - throttles: Number of throttles applied (usually 0)
+# - rule: Object containing rule information (id, name, refillRate, burstRate, isDefault)
+
+# Create a client with default bucket size
+# Note: Both API key and application ID are required for all requests
+client = LightrateClient::Client.new(
+  ENV['LIGHTRATE_API_KEY'] || 'your_api_key_here',
+  ENV['LIGHTRATE_APPLICATION_ID'] || 'your_application_id_here',
+  default_local_bucket_size: 20,  # Default bucket size for all operations
+  logger: ENV['DEBUG'] ? Logger.new(STDOUT) : nil
+)
+
+puts "=== Lightrate Client with Local Token Buckets ==="
+puts
+
+begin
+  # Example 1: Email operation (uses default bucket size)
+  puts "1. Email operation (bucket size: 20):"
+  result1 = client.consume_local_bucket_token(
+    operation: 'operation.one',
+    user_identifier: 'user123'
+  )
+
+  puts "   Success: #{result1.success}"
+  puts "   Used local token: #{result1.used_local_token}"
+  puts "   Bucket status: #{result1.bucket_status}"
+  puts
+
+  # Example 2: SMS operation (uses default bucket size)
+  puts "2. SMS operation (bucket size: 20):"
+  result2 = client.consume_local_bucket_token(
+    operation: 'operation.two',
+    user_identifier: 'user123'
+  )
+
+  puts "   Success: #{result2.success}"
+  puts "   Used local token: #{result2.used_local_token}"
+  puts "   Bucket status: #{result2.bucket_status}"
+  puts
+
+  # Example 3: Notification operation (uses default bucket size)
+  puts "3. Notification operation (bucket size: 20):"
+  result3 = client.consume_local_bucket_token(
+    operation: 'operation.one',
+    user_identifier: 'user123'
+  )
+
+  puts "   Success: #{result3.success}"
+  puts "   Used local token: #{result3.used_local_token}"
+  puts "   Bucket status: #{result3.bucket_status}"
+  puts
+
+  # Example 4: Path-based operation (uses default bucket size)
+  puts "4. Path-based operation (bucket size: 20):"
+  result4 = client.consume_local_bucket_token(
+    path: '/api/v1/emails/send',
+    http_method: 'POST',
+    user_identifier: 'user456'
+  )
+
+  puts "   Success: #{result4.success}"
+  puts "   Used local token: #{result4.used_local_token}"
+  puts "   Bucket status: #{result4.bucket_status}"
+  puts
+
+  # Example 5: Admin path operation (uses default bucket size)
+  puts "5. Admin path operation (bucket size: 20):"
+  result5 = client.consume_local_bucket_token(
+    path: '/api/v1/admin/users/123/notify',
+    http_method: 'POST',
+    user_identifier: 'admin_user'
+  )
+
+  puts "   Success: #{result5.success}"
+  puts "   Used local token: #{result5.used_local_token}"
+  puts "   Bucket status: #{result5.bucket_status}"
+  puts
+
+  # Example 6: Different HTTP methods for same path
+  puts "6. Different HTTP methods for same path:"
+  result6a = client.consume_local_bucket_token(
+    path: '/api/v1/users',
+    http_method: 'GET',
+    user_identifier: 'user123'
+  )
+  result6b = client.consume_local_bucket_token(
+    path: '/api/v1/users',
+    http_method: 'POST',
+    user_identifier: 'user123'
+  )
+  
+  puts "   GET /api/v1/users - Success: #{result6a.success}"
+  puts "   POST /api/v1/users - Success: #{result6b.success}"
+  puts "   (These create separate buckets due to different HTTP methods)"
+  puts
+
+  # Example 7: Direct API call using consume_tokens
+  puts "7. Direct API call using consume_tokens:"
+  api_response = client.consume_tokens(
+    operation: 'send_notification',
+    user_identifier: 'user789',
+    tokens_requested: 3
+  )
+
+  puts "   Tokens consumed: #{api_response.tokens_consumed}"
+  puts "   Tokens remaining: #{api_response.tokens_remaining}"
+  puts "   Throttles: #{api_response.throttles}"
+  puts "   Rule: #{api_response.rule.name} (ID: #{api_response.rule.id})"
+  puts "   Is default rule: #{api_response.rule.is_default}"
+  puts
+
+rescue LightrateClient::UnauthorizedError => e
+  puts "❌ Authentication failed: #{e.message}"
+  puts "   Please check your API key"
+rescue LightrateClient::ForbiddenError => e
+  puts "❌ Access denied: #{e.message}"
+  puts "   Please check your subscription status"
+rescue LightrateClient::TooManyRequestsError => e
+  puts "⚠️  Rate limited: #{e.message}"
+  puts "   Please wait before making more requests"
+rescue LightrateClient::NotFoundError => e
+  puts "❌ Rule not found: #{e.message}"
+  puts "   Please check your operation/path configuration"
+rescue LightrateClient::APIError => e
+  puts "❌ API Error (#{e.status_code}): #{e.message}"
+rescue LightrateClient::NetworkError => e
+  puts "❌ Network error: #{e.message}"
+  puts "   Please check your internet connection"
+rescue LightrateClient::TimeoutError => e
+  puts "❌ Request timed out: #{e.message}"
+rescue => e
+  puts "❌ Unexpected error: #{e.class}: #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+end
+
+puts
+puts "=== Example Complete ==="