io-complyance-unify-sdk 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1575651fce5572033d2f3f37d21415f5169ebc19e78e529b131cd4c8c913c118
+  data.tar.gz: 48df40480ed94d3404d81774a4d5430e1af1215cd7eb183af939fc8691a736a3
+SHA512:
+  metadata.gz: e34ae01a956b530b3bae80f5362343d3f2f376326c64e7276b7397c4fc68233a53e5243908eb25329998d42a39a72a34bf140ab153cb842ea6d01328b7f49b3b
+  data.tar.gz: cb00a9fce2808f4be795565e65103bb5e10323e31f77d80635142c5d88f0b6949ef7b344dd6b62a3704939df1ce4cf01971341031f1bf6213d14827eee7755e6

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial Ruby SDK implementation
+- Configuration system with environment variable and Rails credentials support
+- Basic gem structure with proper gemspec
+- Rails integration with Railtie and generators
+- Exception handling system
+- Source and Environment models
+- Retry configuration system
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+
+- Initial release of ComplyanceSDK for Ruby
+- Basic SDK structure and configuration
+- Rails integration support

data/README.md

@@ -0,0 +1,595 @@
+# GETS Ruby SDK
+
+A Ruby SDK for integrating with the GETS Unify e-invoicing platform. This SDK provides easy-to-use APIs for document submission, payload processing, and multi-country compliance management.
+
+## 🚀 **What Actually Works**
+
+- ✅ **Simple API Configuration** - Minimal setup required
+- ✅ **Type-safe Enums** - DocumentType, Country, Environment, etc.
+- ✅ **Basic Status Helpers** - Check submission states
+- ✅ **Comprehensive Error Handling** - Detailed error messages with suggestions
+- ✅ **HTTP Client** - Robust API communication with timeout handling
+- ✅ **Request/Response Parsing** - Full UnifyResponse structure matching backend
+- ✅ **Retry Detection** - Automatic detection of retryable errors
+- ✅ **Logging** - Comprehensive logging with different levels
+- ✅ **Persistent Queue Manager** - File-based retry queue for failed submissions
+- ✅ **Circuit Breaker** - Prevents cascading failures
+- ✅ **Logical Document Types** - Business-level document classification
+- ✅ **Country Policy Registry** - Country-specific validation rules
+- ✅ **Source Reference** - Simplified source identity management
+
+## 📋 **Current Limitations**
+
+- ⚠️ **Template Management** - Handled server-side (not SDK responsibility)
+- ⚠️ **Limited Countries** - Currently supports SA (Saudi Arabia) and MY (Malaysia) in production
+- ⚠️ **Basic Retry Logic** - File-based queue retry (can be enhanced)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'complyance_sdk'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install complyance_sdk
+```
+
+## Quick Start
+
+### 1. Add Dependency
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'complyance_sdk'
+```
+
+### 2. Configuration
+
+```ruby
+# Configure sources and SDK
+source = ComplyanceSDK::Models::Source.new(
+  type: :first_party,
+  id: "ERP-1",
+  name: "SAP ERP",
+  version: "2024.1"
+)
+
+ComplyanceSDK.configure do |config|
+  config.api_key = "YOUR_API_KEY"
+  config.environment = :sandbox
+  config.add_source(source)
+
+  # Enhanced retry configuration with circuit breaker
+  config.retry_config = ComplyanceSDK::Config::RetryConfig.new(
+    max_attempts: 5,
+    base_delay: 1000, # milliseconds
+    backoff_multiplier: 2.0,
+    circuit_breaker_enabled: true
+  )
+end
+```
+
+### 3. Simple Invoice Submission with Logical Document Types
+
+```ruby
+# Simple invoice submission - automatically routes to tax authority
+payload = {
+  invoice_data: {
+    invoice_number: "INV-123",
+    total_amount: 1000,
+    customer_name: "Acme Corp"
+  }
+}
+
+begin
+  response = ComplyanceSDK.push_to_unify_logical(
+    "ERP-1",                                    # Source name
+    "2024.1",                                   # Source version
+    :tax_invoice_export_invoice,                # Logical document type
+    :sa,                                        # Country
+    :single,                                    # Operation
+    :documents,                                 # Mode
+    :invoicing,                                 # Purpose
+    payload                                     # Business data
+  )
+
+  if response[:status] == 'success'
+    puts "✅ Invoice processed successfully!"
+
+    # Access the rich response data
+    if response[:data]
+      # Check payload storage
+      if response[:data][:payload]
+        puts "Payload ID: #{response[:data][:payload][:payload_id]}"
+        puts "Stored at: #{response[:data][:payload][:stored_at]}"
+      end
+
+      # Check template mapping
+      if response[:data][:template]
+        puts "Template: #{response[:data][:template][:template_name]}"
+        puts "Mapping completed: #{response[:data][:template][:mapping_completed]}"
+      end
+
+      # Check document creation (only for purpose="invoicing")
+      if response[:data][:document]
+        puts "Document ID: #{response[:data][:document][:document_id]}"
+        puts "Created at: #{response[:data][:document][:created_at]}"
+      end
+
+      # Check government submission (only for purpose="invoicing")
+      if response[:data][:submission]
+        puts "Submission status: #{response[:data][:submission][:status]}"
+        puts "Authority: #{response[:data][:submission][:authority]}"
+
+        if response[:data][:submission][:accepted]
+          puts "✅ Successfully submitted to #{response[:data][:submission][:authority]}"
+
+          # Access government response data
+          if response[:data][:submission][:response]
+            puts "UUID: #{response[:data][:submission][:response][:uuid]}"
+            puts "QR Code: #{response[:data][:submission][:response][:qr_code]}"
+          end
+        end
+      end
+    end
+  end
+rescue ComplyanceSDK::Exceptions::SDKException => e
+  handle_error(e)
+end
+```
+
+### 4. Create Mapping Only
+
+```ruby
+# Create mapping template (no full invoice processing)
+payload = {
+  invoice_data: {
+    invoice_id: "INV-001",
+    total_amount: 1500.00,
+    customer_name: "Acme Corp"
+  }
+}
+
+begin
+  response = ComplyanceSDK.create_mapping_logical(
+    "ERP-1",                                    # Source name
+    "2024.1",                                   # Source version
+    :sa,                                        # Country
+    :tax_invoice,                               # Logical document type
+    payload                                     # Sample data
+  )
+
+  if response[:status] == 'success' && response[:data]
+    puts "✅ Mapping created successfully!"
+
+    if response[:data][:template]
+      puts "Template ID: #{response[:data][:template][:template_id]}"
+      puts "Mapping completed: #{response[:data][:template][:mapping_completed]}"
+      puts "Mandatory fields mapped: #{response[:data][:template][:mapped_mandatory_fields]}/#{response[:data][:template][:total_mandatory_fields]}"
+    end
+  end
+rescue ComplyanceSDK::Exceptions::SDKException => e
+  handle_error(e)
+end
+```
+
+## 🎯 **Advanced Usage**
+
+### Custom Destinations
+
+```ruby
+# Submit with custom destinations
+destinations = [
+  # Send to tax authority
+  {
+    type: :tax_authority,
+    country: "SA",
+    authority: "ZATCA",
+    document_type: "tax_invoice"
+  },
+
+  # Send email notification
+  {
+    type: :email,
+    recipients: ["finance@company.com"],
+    subject: "Invoice INV-123 Submitted",
+    message: "Your invoice has been successfully submitted to ZATCA"
+  },
+
+  # Archive for storage
+  { type: :archive }
+]
+
+response = ComplyanceSDK.push_to_unify_logical(
+  "ERP-1",                    # Source name
+  "2024.1",                   # Source version
+  :tax_invoice,               # Logical document type
+  :sa,                        # Country
+  :single,                    # Operation
+  :documents,                 # Mode
+  :invoicing,                 # Purpose
+  payload,                    # Business data
+  destinations                # Custom destinations
+)
+```
+
+### Comprehensive Error Handling
+
+```ruby
+def handle_error(exception)
+  error_detail = exception.context || {}
+
+  puts "❌ Error Code: #{error_detail[:code]}"
+  puts "❌ Message: #{exception.message}"
+
+  # Show suggestion if available
+  if error_detail[:suggestion]
+    puts "💡 Suggestion: #{error_detail[:suggestion]}"
+  end
+
+  # Show documentation link if available
+  if error_detail[:documentation_url]
+    puts "📖 Documentation: #{error_detail[:documentation_url]}"
+  end
+
+  # Show field-specific error if available
+  if error_detail[:field]
+    puts "🎯 Field: #{error_detail[:field]}"
+    if error_detail[:field_value]
+      puts "🎯 Value: #{error_detail[:field_value]}"
+    end
+  end
+
+  # Show validation errors if available
+  if error_detail[:validation_errors] && !error_detail[:validation_errors].empty?
+    puts "📝 Validation Errors:"
+    error_detail[:validation_errors].each do |validation_error|
+      puts "  - #{validation_error[:field]}: #{validation_error[:message]}"
+    end
+  end
+
+  # Check if error is retryable
+  if error_detail[:retryable]
+    puts "🔄 This error can be retried"
+    if error_detail[:retry_after_seconds]
+      puts "⏱️ Retry after: #{error_detail[:retry_after_seconds]} seconds"
+    end
+  end
+
+  # Show additional context if available
+  if error_detail[:context] && !error_detail[:context].empty?
+    puts "📋 Additional Context:"
+    error_detail[:context].each do |key, value|
+      puts "  #{key}: #{value}"
+    end
+  end
+end
+```
+
+### Handle Different Response Scenarios
+
+```ruby
+def process_response(response)
+  unless response[:status] == 'success'
+    puts "❌ Request failed: #{response[:message]}"
+    if response[:error]
+      handle_error(ComplyanceSDK::Exceptions::SDKException.new(response[:error][:message], context: response[:error]))
+    end
+    return
+  end
+
+  unless response[:data]
+    puts "⚠️ No data in response"
+    return
+  end
+
+  data = response[:data]
+
+  # Always present: source, payload, template, processing
+  puts "📦 Source: #{data[:source][:source_id]}"
+  puts "📄 Payload: #{data[:payload][:payload_id]}"
+  puts "🎨 Template: #{data[:template][:template_name]}"
+  puts "⚙️ Purpose: #{data[:processing][:purpose]}"
+
+  # Only for purpose="invoicing": conversion, document, validation, submission
+  if data[:processing][:purpose] == 'invoicing'
+    puts "📋 Full invoicing workflow completed"
+
+    if data[:conversion]
+      puts "🔄 Conversion: #{data[:conversion][:success] ? '✅' : '❌'}"
+    end
+
+    if data[:document]
+      puts "📄 Document: #{data[:document][:document_id]}"
+    end
+
+    if data[:validation]
+      puts "✅ Validation: #{data[:validation][:overall_success] ? '✅' : '❌'}"
+    end
+
+    if data[:submission]
+      puts "📤 Submission: #{data[:submission][:status]}"
+    end
+  else
+    puts "📋 Mapping-only workflow completed"
+  end
+end
+```
+
+## 🔧 **Error Types & Handling**
+
+The SDK provides detailed error information for different scenarios:
+
+```ruby
+# Validation errors
+begin
+  ComplyanceSDK.push_to_unify_logical(...)
+rescue ComplyanceSDK::Exceptions::ValidationError => e
+  if e.context[:code] == :validation_failed
+    # Handle validation errors - check field values
+  end
+end
+
+# Authentication errors
+begin
+  ComplyanceSDK.push_to_unify_logical(...)
+rescue ComplyanceSDK::Exceptions::SDKException => e
+  if e.context[:code] == :authentication_failed
+    # Handle auth errors - check API key
+  end
+end
+
+# Country-specific errors
+begin
+  ComplyanceSDK.push_to_unify_logical(...)
+rescue ComplyanceSDK::Exceptions::ValidationError => e
+  if e.context[:code] == :zatca_validation_failed
+    # Handle Saudi Arabia specific validation errors
+  end
+end
+
+# Network/API errors (retryable)
+begin
+  ComplyanceSDK.push_to_unify_logical(...)
+rescue ComplyanceSDK::Exceptions::SDKException => e
+  if e.context[:retryable]
+    # Implement retry logic
+    retry_after = e.context[:retry_after_seconds]
+    # Wait and retry
+  end
+end
+```
+
+## 📊 **Response Structure**
+
+The SDK properly parses the complete backend response:
+
+```ruby
+response = ComplyanceSDK.push_to_unify_logical(...)
+
+# Main response
+response[:status]        # "success" or "error"
+response[:message]       # Response message
+response[:data]          # Response data (nil if error)
+
+# Response data
+response[:data][:source]      # Source information
+response[:data][:payload]     # Payload storage info
+response[:data][:template]    # Template mapping info
+response[:data][:processing]  # Processing metadata
+
+# Only for purpose="invoicing"
+response[:data][:conversion]  # Conversion results
+response[:data][:document]    # Document creation
+response[:data][:validation]  # Validation results
+response[:data][:submission]  # Government submission
+```
+
+## 🔄 **Queue Management**
+
+The Ruby SDK includes a persistent queue manager for handling failed submissions:
+
+```ruby
+# Get queue status
+status = ComplyanceSDK.queue_status
+puts "Pending: #{status[:pending_count]}"
+puts "Processing: #{status[:processing_count]}"
+puts "Failed: #{status[:failed_count]}"
+puts "Success: #{status[:success_count]}"
+
+# Retry failed submissions
+ComplyanceSDK.retry_failed_submissions
+
+# Process pending submissions manually
+ComplyanceSDK.process_pending_submissions
+
+# Clean up old success files (keep last 7 days)
+ComplyanceSDK.cleanup_old_success_files(7)
+
+# Emergency cleanup - clear all queues
+ComplyanceSDK.clear_all_queues
+
+# Clean up duplicate files
+ComplyanceSDK.cleanup_duplicate_files
+```
+
+## 🧪 **Testing Your Integration**
+
+```ruby
+require 'rspec'
+
+RSpec.describe "Invoice Submission" do
+  before do
+    # Configure SDK for testing
+    source = ComplyanceSDK::Models::Source.new(
+      type: :first_party,
+      id: "TEST-1",
+      name: "Test Source",
+      version: "1.0"
+    )
+
+    ComplyanceSDK.configure do |config|
+      config.api_key = "test-api-key"
+      config.environment = :sandbox
+      config.add_source(source)
+    end
+  end
+
+  it "successfully submits an invoice" do
+    # Prepare payload
+    payload = {
+      invoice_data: {
+        invoice_number: "TEST-001",
+        total_amount: 100.00,
+        currency: "SAR"
+      }
+    }
+
+    # Submit and verify
+    response = ComplyanceSDK.submit_invoice_logical(
+      "TEST-1", "1.0", :sa, :tax_invoice, payload
+    )
+
+    expect(response[:status]).to eq('success')
+    expect(response[:data]).not_to be_nil
+    expect(response[:data][:payload][:payload_id]).not_to be_nil
+  end
+
+  it "handles validation errors" do
+    # Test invalid payload
+    invalid_payload = {} # Empty payload
+
+    expect {
+      ComplyanceSDK.submit_invoice_logical(
+        "TEST-1", "1.0", :sa, :tax_invoice, invalid_payload
+      )
+    }.to raise_error(ComplyanceSDK::Exceptions::ValidationError)
+  end
+end
+```
+
+## Environment Variables
+
+```ruby
+# Configure from environment variables
+ComplyanceSDK.configure_from_env
+```
+
+Required environment variables:
+
+- `COMPLYANCE_API_KEY`: Your API key
+- `COMPLYANCE_ENVIRONMENT`: Environment (dev, test, stage, local, sandbox, simulation, production)
+
+Optional environment variables:
+
+- `COMPLYANCE_LOGGING_ENABLED`: Enable or disable logging (true, false)
+- `COMPLYANCE_LOG_LEVEL`: Log level (debug, info, warn, error)
+
+## Rails Integration
+
+In a Rails application, the SDK can be configured using Rails credentials:
+
+```ruby
+# config/initializers/complyance_sdk.rb
+ComplyanceSDK.configure_from_rails
+```
+
+Add your API key to your credentials:
+
+```yaml
+# rails credentials:edit
+complyance:
+  api_key: your_api_key_here
+  environment: sandbox
+```
+
+Or use environment-specific credentials:
+
+```yaml
+complyance:
+  development:
+    api_key: your_development_api_key
+    environment: sandbox
+  production:
+    api_key: your_production_api_key
+    environment: production
+```
+
+## 📚 **API Reference**
+
+### Core Methods
+
+- `ComplyanceSDK.configure(config)` - Initialize SDK
+- `ComplyanceSDK.push_to_unify_logical(...)` - Complete workflow with logical document types
+- `ComplyanceSDK.submit_invoice_logical(...)` - Complete invoicing workflow
+- `ComplyanceSDK.create_mapping_logical(...)` - Create mapping templates only
+- `ComplyanceSDK.push_to_unify_with_source_ref(...)` - Full control with SourceRef
+
+### Helper Methods
+
+- `response[:status] == 'success'` - Check if request succeeded
+- `response[:error]` - Check if request has errors
+- `submission[:accepted]` - Check if government accepted submission
+- `processing[:purpose] == 'invoicing'` - Check if full invoicing workflow
+
+### Error Handling
+
+- `error[:retryable]` - Check if error can be retried
+- `error[:suggestion]` - Get helpful suggestion
+- `error[:validation_errors]` - Get field-level validation errors
+
+### Queue Management
+
+- `ComplyanceSDK.queue_status` - Get queue statistics
+- `ComplyanceSDK.retry_failed_submissions` - Retry failed submissions
+- `ComplyanceSDK.process_pending_submissions` - Process pending submissions manually
+- `ComplyanceSDK.clear_all_queues` - Emergency cleanup
+
+For detailed documentation and examples, visit [https://docs.complyance.io](https://docs.complyance.io)
+
+---
+
+## 🎯 **What's Next?**
+
+This SDK provides a solid foundation for e-invoicing integration with:
+
+- ✅ Proper request/response handling
+- ✅ Comprehensive error management
+- ✅ Rich response parsing
+- ✅ Type-safe operations
+- ✅ Persistent queue management
+- ✅ Circuit breaker pattern
+- ✅ Logical document types
+- ✅ Country-specific validation
+
+Future enhancements may include:
+
+- 🔄 Redis-based retry strategies
+- 🌍 Extended country support
+- 🔒 Enhanced security features
+- 📊 Built-in analytics and monitoring
+
+## 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/complyance-io/sdk-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).