thelawin 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3d2a3941184fa5825fee25c391e076ed69bd79c0ec6ed6f506da48ebe12e5c3
+  data.tar.gz: d58661f8129b7a75bc4e6e4a68e583cc726051dc8d031d678eb869c6157800ba
+SHA512:
+  metadata.gz: 27fbf690097b55c35dbb667efdf8471d63a9e57875135d8ebd79752fbef5753460d154651b5359f0c105bc1bfcc8ceb67446579dbc257ef46d4406f056ed6a75
+  data.tar.gz: e5e0a0641e4f936708f48770d6874eb7bdc0d55beaea71fdaefd339d997a4f726a0209266fd0b721e3175bc83eba8e7fc0c83d242b25e648d47b2864b46745ca

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 thelawin.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,418 @@
+# Thelawin Ruby SDK
+
+Official Ruby SDK for [thelawin.dev](https://thelawin.dev) - Generate ZUGFeRD/Factur-X/XRechnung/Peppol/FatturaPA compliant invoices with a simple API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'thelawin', git: 'https://github.com/steviee/thelawin-clients.git', glob: 'ruby/*.gemspec'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require 'thelawin'
+
+client = Thelawin::Client.new(api_key: 'env_sandbox_xxx')
+
+result = client.invoice
+  .number('2026-001')
+  .date('2026-01-15')
+  .seller(
+    name: 'Acme GmbH',
+    vat_id: 'DE123456789',
+    street: 'Hauptstraße 1',
+    city: 'Berlin',
+    postal_code: '10115',
+    country: 'DE'
+  )
+  .buyer(
+    name: 'Customer AG',
+    city: 'München',
+    country: 'DE'
+  )
+  .add_item(
+    description: 'Consulting Services',
+    quantity: 8,
+    unit: 'HUR',
+    unit_price: 150.00,
+    vat_rate: 19.0
+  )
+  .template('minimal')
+  .generate
+
+if result.success?
+  result.save_pdf('./invoices/2026-001.pdf')
+  puts "Generated: #{result.filename}"
+  puts "Format: #{result.format.format_used}"  # => "zugferd"
+else
+  result.errors.each do |error|
+    puts "#{error[:path]}: #{error[:message]}"
+  end
+end
+```
+
+## Configuration
+
+You can configure the client globally:
+
+```ruby
+Thelawin.configure do |config|
+  config.api_key = 'env_live_xxx'
+  config.environment = :production  # :production or :preview
+  config.timeout = 30               # optional
+end
+
+# Then create clients without passing options
+client = Thelawin::Client.new
+
+# Or use the global client directly
+Thelawin.client.invoice.number('2026-001')...
+```
+
+### Environments
+
+| Environment | URL | Description |
+|-------------|-----|-------------|
+| `:production` | `https://api.thelawin.dev` | Production API (default) |
+| `:preview` | `https://api.preview.thelawin.dev:3080` | Preview/staging API |
+
+```ruby
+# Use preview environment globally
+Thelawin.configure do |config|
+  config.api_key = 'env_sandbox_xxx'
+  config.environment = :preview
+end
+
+# Or per-client
+client = Thelawin::Client.new(
+  api_key: 'env_sandbox_xxx',
+  environment: :preview
+)
+
+# Check environment
+client.preview?     # => true
+client.production?  # => false
+
+# Custom URL (overrides environment)
+client = Thelawin::Client.new(
+  api_key: 'env_sandbox_xxx',
+  base_url: 'http://localhost:8080'
+)
+```
+
+## Supported Formats
+
+| Format | Description | Output |
+|--------|-------------|--------|
+| `auto` | Auto-detect based on countries (default) | PDF or XML |
+| `zugferd` | ZUGFeRD 2.3 (Germany/EU) | PDF/A-3 + CII XML |
+| `facturx` | Factur-X 1.0 (France) | PDF/A-3 + CII XML |
+| `xrechnung` | XRechnung 3.0 (German B2G) | PDF/A-3 + UBL XML |
+| `pdf` | Plain PDF without XML | PDF |
+| `ubl` | UBL 2.1 Invoice | XML only |
+| `cii` | UN/CEFACT CII | XML only |
+| `peppol` | Peppol BIS Billing 3.0 | XML only |
+| `fatturapa` | FatturaPA 1.2.1 (Italy) | XML only |
+
+## API Reference
+
+### InvoiceBuilder
+
+Fluent builder for creating invoices:
+
+```ruby
+client.invoice
+  # Required fields
+  .number(value)                     # Invoice number
+  .date(value)                       # Date string or Date object
+  .seller(name:, **opts)             # Seller info
+  .buyer(name:, **opts)              # Buyer info
+  .add_item(description:, quantity:, unit_price:, **opts)
+
+  # Format & Profile
+  .format('zugferd')                 # Output format (default: 'auto')
+  .profile('en16931')                # Profile level (default: 'en16931')
+
+  # Optional invoice fields
+  .due_date(value)                   # Payment due date
+  .currency('EUR')                   # Currency code (default: 'EUR')
+  .notes('Thank you!')               # Invoice notes/comments
+  .payment(iban:, bic:, terms:)      # Payment information
+
+  # Format-specific fields
+  .leitweg_id('04011000-12345-67')   # XRechnung: German B2G routing
+  .buyer_reference('PO-12345')       # Peppol: Purchase order reference
+  .tipo_documento('TD01')            # FatturaPA: Document type
+
+  # Customization
+  .template('minimal')               # 'minimal', 'classic', 'compact'
+  .locale('de')                      # 'de', 'en', 'fr', 'es', 'it'
+  .logo_file('./logo.png', width_mm: 30)
+  .footer_text('Thank you!')
+  .accent_color('#8b5cf6')
+
+  # Execute
+  .generate                          # Generate invoice
+  .validate                          # Dry-run validation only
+```
+
+### Party (seller/buyer)
+
+```ruby
+Thelawin::Party.new(
+  name: 'Company Name',              # Required
+  street: 'Street Address',
+  city: 'City',
+  postal_code: '12345',
+  country: 'DE',                     # ISO 3166-1 alpha-2
+  vat_id: 'DE123456789',
+  email: 'email@example.com',
+  phone: '+49 30 12345678',
+  # Peppol-specific
+  peppol_id: '0088:1234567890123',   # EAS:ID format
+  # FatturaPA-specific (Italy)
+  codice_fiscale: 'RSSMRA80A01H501U',
+  codice_destinatario: 'ABCDEFG',    # SDI code (7 chars)
+  pec: 'email@pec.it'                # Certified email
+)
+```
+
+### LineItem
+
+```ruby
+Thelawin::LineItem.new(
+  description: 'Service',            # Required
+  quantity: 8.0,                     # Required
+  unit_price: 150.00,                # Required
+  unit: 'HUR',                       # UN/ECE Rec 20 code (default: 'C62')
+  vat_rate: 19.0,                    # Default: 19.0
+  natura: 'N2.2'                     # FatturaPA: VAT exemption code
+)
+```
+
+### Common Unit Codes
+
+| Code | Description |
+|------|-------------|
+| `C62` | Piece (default) |
+| `HUR` | Hour |
+| `DAY` | Day |
+| `MON` | Month |
+| `KGM` | Kilogram |
+| `MTR` | Meter |
+| `LTR` | Liter |
+
+### Result Handling
+
+```ruby
+result = client.invoice.generate
+
+if result.success?
+  puts result.filename              # 'invoice-2026-001.pdf' or '.xml'
+  puts result.format.format_used    # 'zugferd', 'fatturapa', etc.
+  puts result.format.profile        # 'EN16931'
+  puts result.format.version        # '2.3'
+
+  # Check output type
+  if result.xml_only?
+    result.save('./invoice.xml')
+  else
+    result.save_pdf('./invoice.pdf')
+  end
+
+  # Legal warnings
+  result.warnings.each do |warning|
+    puts "#{warning.code}: #{warning.message}"
+    puts "Legal basis: #{warning.legal_basis}"
+  end
+else
+  result.errors.each do |error|
+    puts "#{error[:path]}: #{error[:message]}"
+  end
+end
+```
+
+### Pre-Validation (Dry-Run)
+
+Validate invoice data without generating PDF:
+
+```ruby
+result = client.invoice
+  .number('2026-001')
+  .date('2026-01-15')
+  .seller(name: 'Acme', country: 'DE')
+  .buyer(name: 'Customer', country: 'IT')
+  .add_item(description: 'Service', quantity: 1, unit_price: 100)
+  .format('fatturapa')
+  .validate  # Dry-run validation
+
+if result.valid?
+  puts "Valid! Would generate: #{result.format.format_used}"
+else
+  result.errors.each { |e| puts e }
+end
+```
+
+### Account Info
+
+```ruby
+account = client.account
+puts account.plan           # => "starter"
+puts account.remaining      # => 450
+puts account.overage_count  # => 0
+```
+
+## Error Handling
+
+```ruby
+begin
+  result = client.invoice.number('2026-001').generate
+
+  unless result.success?
+    # Validation errors (422)
+    result.errors.each do |error|
+      puts "#{error[:path]}: #{error[:message]}"
+    end
+  end
+rescue Thelawin::QuotaExceededError
+  puts 'Quota exceeded, upgrade your plan'
+rescue Thelawin::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Thelawin::ApiError => e
+  puts "API error #{e.status_code}: #{e.message}"
+end
+```
+
+## Format-Specific Examples
+
+### XRechnung (German B2G)
+
+```ruby
+result = client.invoice
+  .format('xrechnung')
+  .leitweg_id('04011000-12345-67')  # Required for B2G
+  .seller(
+    name: 'Acme GmbH',
+    vat_id: 'DE123456789',
+    email: 'invoice@acme.de',       # Required for XRechnung
+    street: 'Hauptstraße 1',
+    city: 'Berlin',
+    postal_code: '10115',
+    country: 'DE'
+  )
+  # ... rest of invoice
+  .generate
+```
+
+### Peppol
+
+```ruby
+result = client.invoice
+  .format('peppol')
+  .buyer_reference('PO-12345')
+  .seller(
+    name: 'Acme Ltd',
+    vat_id: 'GB123456789',
+    peppol_id: '0088:1234567890123',
+    # ...
+  )
+  .buyer(
+    name: 'Customer BV',
+    peppol_id: '0106:NL123456789B01',
+    # ...
+  )
+  .generate
+```
+
+### FatturaPA (Italy)
+
+```ruby
+result = client.invoice
+  .format('fatturapa')
+  .tipo_documento('TD01')  # TD01=invoice, TD04=credit note
+  .seller(
+    name: 'Acme S.r.l.',
+    vat_id: 'IT12345678901',
+    codice_fiscale: '12345678901',
+    street: 'Via Roma 1',
+    city: 'Milano',
+    postal_code: '20100',
+    country: 'IT'
+  )
+  .buyer(
+    name: 'Cliente S.p.A.',
+    vat_id: 'IT98765432109',
+    codice_destinatario: 'ABCDEFG',  # SDI code
+    # OR: pec: 'cliente@pec.it'
+    city: 'Roma',
+    country: 'IT'
+  )
+  .add_item(
+    description: 'Consulenza',
+    quantity: 10,
+    unit_price: 100,
+    vat_rate: 22.0
+  )
+  .generate
+
+# FatturaPA returns XML only
+result.save('./fattura.xml')
+```
+
+## Rails Integration
+
+```ruby
+# config/initializers/thelawin.rb
+Thelawin.configure do |config|
+  config.api_key = Rails.application.credentials.thelawin_api_key
+  config.environment = Rails.env.production? ? :production : :preview
+end
+
+# In your service
+class InvoiceService
+  def generate_invoice(order)
+    Thelawin.client.invoice
+      .number(order.invoice_number)
+      .date(order.created_at.to_date)
+      .seller(company_details)
+      .buyer(customer_party(order.customer))
+      .items(order.line_items.map { |li| line_item_attrs(li) })
+      .generate
+  end
+
+  private
+
+  def company_details
+    Thelawin::Party.new(
+      name: 'My Company',
+      vat_id: ENV['COMPANY_VAT_ID'],
+      street: '123 Main St',
+      city: 'Berlin',
+      postal_code: '10115',
+      country: 'DE'
+    )
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rspec` to run the tests.
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/thelawin/client.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "fileutils"
+
+module Thelawin
+  # Main client for interacting with the thelawin.dev API
+  class Client
+    attr_reader :api_key, :base_url, :timeout, :environment
+
+    # Create a new Thelawin Client
+    # @param api_key [String] Your API key (env_sandbox_* or env_live_*)
+    # @param environment [Symbol] :production or :preview (default: from config or :production)
+    # @param base_url [String] Custom API base URL (overrides environment)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    def initialize(api_key: nil, environment: nil, base_url: nil, timeout: nil)
+      @api_key = api_key || Thelawin.configuration.api_key
+      @environment = environment || Thelawin.configuration.environment
+      @timeout = timeout || Thelawin.configuration.timeout
+
+      # Use custom base_url if provided, otherwise use environment default
+      @base_url = base_url || Thelawin::ENVIRONMENTS[@environment]
+
+      raise ArgumentError, "API key is required" if @api_key.nil? || @api_key.empty?
+    end
+
+    # Check if using preview environment
+    # @return [Boolean]
+    def preview?
+      @environment == :preview
+    end
+
+    # Check if using production environment
+    # @return [Boolean]
+    def production?
+      @environment == :production
+    end
+
+    # Backwards compatibility alias
+    alias api_url base_url
+
+    # Create a new invoice builder with fluent API
+    # @return [InvoiceBuilder]
+    def invoice
+      InvoiceBuilder.new(self)
+    end
+
+    # Pre-validate invoice data without generating PDF (dry-run)
+    # @param request [Hash] Invoice request data
+    # @return [DryRunResult]
+    def validate(request)
+      response = connection.post("/v1/validate") do |req|
+        req.body = request.to_json
+      end
+
+      data = handle_response(response)
+      DryRunResult.new(data)
+    end
+
+    # Get account information (quota, plan, etc.)
+    # @return [AccountInfo]
+    def account
+      response = connection.get("/v1/account")
+      data = handle_response(response)
+      AccountInfo.new(data)
+    end
+
+    private
+
+    def generate_invoice_internal(request)
+      response = connection.post("/v1/generate") do |req|
+        req.body = request.to_json
+      end
+
+      handle_generate_response(response)
+    rescue Faraday::TimeoutError
+      raise NetworkError, "Request timeout"
+    rescue Faraday::ConnectionFailed => e
+      raise NetworkError.new("Connection failed", e)
+    end
+
+    def validate_invoice_internal(request)
+      response = connection.post("/v1/validate") do |req|
+        req.body = request.to_json
+      end
+
+      handle_validate_response(response)
+    rescue Faraday::TimeoutError
+      raise NetworkError, "Request timeout"
+    rescue Faraday::ConnectionFailed => e
+      raise NetworkError.new("Connection failed", e)
+    end
+
+    def handle_generate_response(response)
+      case response.status
+      when 200
+        data = JSON.parse(response.body)
+        InvoiceSuccess.new(
+          pdf_base64: data["pdfBase64"],
+          filename: data["filename"],
+          format: FormatInfo.new(data["format"]),
+          account: data["account"] ? AccountInfo.new(data["account"]) : nil
+        )
+      when 402
+        data = JSON.parse(response.body)
+        raise QuotaExceededError, data["message"] || "Quota exceeded"
+      when 422
+        data = JSON.parse(response.body)
+        if data["details"]
+          InvoiceFailure.new(errors: data["details"].map { |e| e.transform_keys(&:to_sym) })
+        else
+          raise ApiError.new(data["message"] || data["error"], response.status, data["error"])
+        end
+      else
+        data = JSON.parse(response.body) rescue { "error" => "unknown_error", "message" => "HTTP #{response.status}" }
+        raise ApiError.new(data["message"] || data["error"], response.status, data["error"])
+      end
+    end
+
+    def handle_validate_response(response)
+      case response.status
+      when 200
+        data = JSON.parse(response.body)
+        DryRunResult.new(data)
+      when 422
+        data = JSON.parse(response.body)
+        if data["details"]
+          InvoiceFailure.new(errors: data["details"].map { |e| e.transform_keys(&:to_sym) })
+        else
+          DryRunResult.new(data)
+        end
+      else
+        data = JSON.parse(response.body) rescue { "error" => "unknown_error", "message" => "HTTP #{response.status}" }
+        raise ApiError.new(data["message"] || data["error"], response.status, data["error"])
+      end
+    end
+
+    def handle_response(response)
+      unless response.success?
+        data = JSON.parse(response.body) rescue { "error" => "unknown_error" }
+        raise ApiError.new(data["message"] || data["error"], response.status, data["error"])
+      end
+
+      JSON.parse(response.body)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |f|
+        f.request :retry, max: 2, interval: 0.5
+        f.headers["Content-Type"] = "application/json"
+        f.headers["X-API-Key"] = @api_key
+        f.options.timeout = @timeout
+        f.options.open_timeout = 10
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/thelawin/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Thelawin
+  # Base error class for all Thelawin SDK errors
+  class Error < StandardError; end
+
+  # Error raised when the API returns validation errors
+  class ValidationError < Error
+    attr_reader :errors, :status_code
+
+    def initialize(errors, status_code = 422)
+      @errors = errors
+      @status_code = status_code
+      message = errors.map { |e| "#{e[:path]}: #{e[:message]}" }.join("; ")
+      super("Validation failed: #{message}")
+    end
+
+    # Get a user-friendly error message
+    # @return [String]
+    def to_user_message
+      @errors.map { |e| "- #{e[:path]}: #{e[:message]}" }.join("\n")
+    end
+  end
+
+  # Error raised when the API returns an HTTP error
+  class ApiError < Error
+    attr_reader :status_code, :code
+
+    def initialize(message, status_code, code = nil)
+      @status_code = status_code
+      @code = code
+      super(message)
+    end
+  end
+
+  # Error raised when a network request fails
+  class NetworkError < Error
+    attr_reader :cause
+
+    def initialize(message, cause = nil)
+      @cause = cause
+      super(message)
+    end
+  end
+
+  # Error raised when quota is exceeded
+  class QuotaExceededError < ApiError
+    def initialize(message)
+      super(message, 402, "quota_exceeded")
+    end
+  end
+end