pdfx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 125dd0c7576da8187166eb9764471eff0eae685a051243b34b81efa38e037ee8
+  data.tar.gz: 16845fc743aff9ba65790b1017625de2f915ab5a61d557da7d5693935bec5a46
+SHA512:
+  metadata.gz: 3770b595eb79c8b0ddb64c8aa3457f546c886b5bd6f382aceebb885fa3b9d14148025d859a955dd771ee122d2e9b7be5b319ccf3023a063c25b12be5ffcbe6ac
+  data.tar.gz: '048946256d8d7cf96c81facc3c15a803df3f6a9bf15e9e17735b72ad2c4eb4d12e71da52514eebbd75d99f154bb6932440eb9609be36d569474fc76a695c358c'

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 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).
+
+## [0.1.0] - 2025-11-30
+
+### Added
+- Initial release
+- `Pdfx::Client` class for API interactions
+- Support for template-based PDF generation
+- Data interpolation support
+- X-Api-Key authentication
+- Comprehensive error handling with custom exception classes
+- Configuration module for global settings
+- Documentation and examples

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Olivier Bonnaure
+
+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,175 @@
+# Pdfx Ruby Gem
+
+A Ruby wrapper for the [pdfx.fr](https://pdfx.fr) API - the fastest, most eco-friendly PDF generation service for developers.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pdfx'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install pdfx
+```
+
+## Configuration
+
+Configure the gem with your API key:
+
+```ruby
+require 'pdfx'
+
+Pdfx.configure do |config|
+  config.api_key = "your-api-key-here"
+end
+```
+
+You can also set a custom base URL (useful for testing):
+
+```ruby
+Pdfx.configure do |config|
+  config.api_key = "your-api-key-here"
+  config.base_url = "https://custom-pdfx-instance.com"
+end
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'pdfx'
+
+# Configure globally
+Pdfx.configure do |config|
+  config.api_key = "your-api-key"
+end
+
+# Create a client
+client = Pdfx::Client.new
+
+# Generate a PDF
+pdf_data = client.generate_pdf(
+  template_uuid: "ea99e8b9-1234-5678-90ab-cdef12345678",
+  data: {
+    invoice: "001",
+    customer: "Acme Corp",
+    amount: 1299
+  }
+)
+
+# Save to file
+File.write("invoice.pdf", pdf_data)
+```
+
+### Using Client-Specific API Key
+
+You can override the global API key for specific clients:
+
+```ruby
+client = Pdfx::Client.new(api_key: "different-api-key")
+
+pdf_data = client.generate_pdf(
+  template_uuid: "ea99e8b9-1234-5678-90ab-cdef12345678",
+  data: { invoice: "002", customer: "Beta Inc", amount: 2500 }
+)
+```
+
+### Error Handling
+
+The gem provides specific error classes for different scenarios:
+
+```ruby
+begin
+  pdf_data = client.generate_pdf(
+    template_uuid: "ea99e8b9-1234-5678-90ab-cdef12345678",
+    data: { invoice: "003" }
+  )
+  File.write("output.pdf", pdf_data)
+rescue Pdfx::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Pdfx::RequestError => e
+  puts "Bad request: #{e.message}"
+rescue Pdfx::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Pdfx::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Pdfx::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+## API Reference
+
+### `Pdfx.configure`
+
+Configure the gem globally.
+
+**Parameters:**
+- `api_key` (String): Your pdfx.fr API key
+- `base_url` (String): Base URL for the API (default: "https://pdfx.fr")
+
+### `Pdfx::Client.new`
+
+Create a new client instance.
+
+**Parameters:**
+- `api_key` (String, optional): Override the global API key
+- `base_url` (String, optional): Override the global base URL
+
+### `client.generate_pdf`
+
+Generate a PDF using a template.
+
+**Parameters:**
+- `template_uuid` (String, required): The UUID of your template
+- `data` (Hash, optional): Data to interpolate into the template
+
+**Returns:** String (PDF binary data)
+
+**Raises:**
+- `Pdfx::AuthenticationError`: Invalid API key
+- `Pdfx::RequestError`: Invalid request parameters
+- `Pdfx::ServerError`: Server error (5xx)
+- `Pdfx::NetworkError`: Network connectivity issues
+
+## Error Classes
+
+- `Pdfx::Error` - Base error class
+- `Pdfx::AuthenticationError` - Invalid API key (401)
+- `Pdfx::RequestError` - Bad request (400)
+- `Pdfx::ServerError` - Server error (5xx)
+- `Pdfx::NetworkError` - Network connectivity issues
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/solisoft/ruby-pdfx.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## About pdfx.fr
+
+[pdfx.fr](https://pdfx.fr) is a blazing-fast PDF generation API that:
+- Generates PDFs in sub-100ms
+- Supports Factur-X/ZUGFeRD e-invoicing
+- Stores zero data (privacy by design)
+- Runs on 100% renewable energy
+- Offers 200 free PDFs per month
+
+Visit [pdfx.fr](https://pdfx.fr) to create your account and get your API key.

data/lib/pdfx/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Pdfx
+  # Main client class for interacting with the pdfx.fr API
+  class Client
+    attr_reader :api_key, :base_url
+
+    # Initialize a new Pdfx client
+    #
+    # @param api_key [String] Your pdfx.fr API key (optional if configured globally)
+    # @param base_url [String] The base URL for the API (defaults to https://pdfx.fr)
+    def initialize(api_key: nil, base_url: nil)
+      @api_key = api_key || Pdfx.api_key
+      @base_url = base_url || Pdfx.base_url
+
+      raise ArgumentError, "API key is required" if @api_key.nil? || @api_key.empty?
+    end
+
+    # Generate a PDF using a template and data
+    #
+    # @param template_uuid [String] The UUID of the template to use
+    # @param data [Hash] The data to interpolate into the template
+    # @return [String] The PDF binary data
+    # @raise [Pdfx::AuthenticationError] If the API key is invalid
+    # @raise [Pdfx::RequestError] If the request parameters are invalid
+    # @raise [Pdfx::ServerError] If the server returns an error
+    # @raise [Pdfx::NetworkError] If a network error occurs
+    #
+    # @example Generate a PDF
+    #   client = Pdfx::Client.new(api_key: "your-api-key")
+    #   pdf_data = client.generate_pdf(
+    #     template_uuid: "ea99e8b9-...",
+    #     data: { invoice: "001", customer: "Acme", amount: 1299 }
+    #   )
+    #   File.write("invoice.pdf", pdf_data)
+    def generate_pdf(template_uuid:, data: {})
+      raise ArgumentError, "template_uuid is required" if template_uuid.nil? || template_uuid.empty?
+
+      payload = {
+        template_uuid: template_uuid,
+        data: data
+      }
+
+      make_request(payload)
+    end
+
+    private
+
+    # Make an HTTP POST request to the pdfx.fr API
+    #
+    # @param payload [Hash] The request payload
+    # @return [String] The PDF binary data
+    def make_request(payload)
+      uri = URI.join(@base_url, "/v1")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 30 # 30 seconds timeout
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request["X-Api-Key"] = @api_key
+      request.body = JSON.generate(payload)
+
+      response = http.request(request)
+
+      handle_response(response)
+    rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError, "Network error: #{e.message}"
+    end
+
+    # Handle the HTTP response
+    #
+    # @param response [Net::HTTPResponse] The HTTP response
+    # @return [String] The PDF binary data
+    def handle_response(response)
+      case response.code.to_i
+      when 200
+        response.body
+      when 401
+        raise AuthenticationError, "Invalid API key"
+      when 400
+        error_message = extract_error_message(response.body)
+        raise RequestError, "Bad request: #{error_message}"
+      when 500..599
+        raise ServerError, "Server error: #{response.code}"
+      else
+        raise Error, "Unexpected response: #{response.code}"
+      end
+    end
+
+    # Extract error message from response body
+    #
+    # @param body [String] The response body
+    # @return [String] The error message
+    def extract_error_message(body)
+      JSON.parse(body)["error"] || body
+    rescue JSON::ParserError
+      body
+    end
+  end
+end

data/lib/pdfx/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pdfx
+  # Base error class for all Pdfx errors
+  class Error < StandardError; end
+
+  # Raised when authentication fails (invalid API key)
+  class AuthenticationError < Error; end
+
+  # Raised when the request is invalid (bad parameters)
+  class RequestError < Error; end
+
+  # Raised when the server returns a 5xx error
+  class ServerError < Error; end
+
+  # Raised when a network error occurs
+  class NetworkError < Error; end
+end

data/lib/pdfx/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pdfx
+  VERSION = "0.1.0"
+end

data/lib/pdfx.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "pdfx/version"
+require_relative "pdfx/errors"
+require_relative "pdfx/client"
+
+# Main module for the Pdfx gem
+module Pdfx
+  class << self
+    attr_accessor :api_key, :base_url
+
+    # Configure the Pdfx gem
+    #
+    # @yield [self] Configuration block
+    #
+    # @example Configure with a block
+    #   Pdfx.configure do |config|
+    #     config.api_key = "your-api-key"
+    #     config.base_url = "https://pdfx.fr"
+    #   end
+    def configure
+      yield self if block_given?
+    end
+  end
+
+  # Set default configuration
+  self.base_url = "https://pdfx.fr"
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: pdfx
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Olivier Bonnaure
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-30 00:00:00.000000000 Z
+dependencies: []
+description: A simple and efficient Ruby gem for generating PDFs using the pdfx.fr
+  API with template-based data interpolation
+email:
+- olivier@solisoft.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/pdfx.rb
+- lib/pdfx/client.rb
+- lib/pdfx/errors.rb
+- lib/pdfx/version.rb
+homepage: https://github.com/solisoft/ruby-pdfx
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/solisoft/ruby-pdfx
+  source_code_uri: https://github.com/solisoft/ruby-pdfx
+  changelog_uri: https://github.com/solisoft/ruby-pdfx/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Ruby wrapper for the pdfx.fr API
+test_files: []