RubyGems - pdfify-client - Versions diffs - 0.1.0 - Mend

pdfify-client 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 658d0d93dae647bc25b7610eea5314ac06496453fddd0ced2d0e19e5cd497629
+  data.tar.gz: d5658389ef7da0b6db2a1121b01997bdf8042bfde084639ad98e50bb54a5f286
+SHA512:
+  metadata.gz: 0f387017b286d41b50a8eeb6ca9c81140d160d46f63199c293547e7a14373f0ccfd73623c73d0a6a6be6d10a3dd222306f9847efed9ca74872c5657c163e3f13
+  data.tar.gz: 586a730c20cafc9d274a24a7b4dcdba56812ae086aacc480aabf3e93a7b0cc8c80e9472c68581de885d12a1a26a372ab5f4bc2aa4de69d9494291868902b7e4f

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,28 @@
+# 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] - 2026-01-25
+### Added
+- Initial release of PDFify Ruby gem
+- Basic HTML to PDF conversion via PDFify API
+- Configuration support for API key, base URL, and timeout
+- Error handling for common API errors (quota, validation, auth)
+- Support for test/sandbox mode
+- Support for advanced options (profile, css, auto_compat, template_engine)
+- Comprehensive documentation and examples
+- Rails integration examples
+- DocRaptor migration guide
+### Features
+- `PDFify.configure` for global configuration
+- `PDFify.convert` convenience method
+- `PDFify::Client` class for instance-based usage
+- Custom error classes for better error handling
+- HTTParty-based HTTP client
+[0.1.0]: https://github.com/yourusername/pdfify-ruby/releases/tag/v0.1.0

data/LICENSE.txt ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 PDFify
+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 ADDED Viewed

@@ -0,0 +1,465 @@
+# PDFify Ruby Gem
+Ruby client library for the [PDFify](https://pdfify.example.com) HTML-to-PDF API. A DocRaptor alternative at 50% cheaper pricing.
+## Installation
+Add this line to your application's Gemfile:
+```ruby
+gem 'pdfify'
+```
+And then execute:
+```bash
+bundle install
+```
+Or install it yourself as:
+```bash
+gem install pdfify
+```
+## Quick Start
+```ruby
+require 'pdfify'
+# Configure with your API key
+PDFify.configure do |config|
+  config.api_key = "pfy_live_xxxxxxxxxx"
+  config.base_url = "https://api.pdfify.example.com"  # optional
+  config.timeout = 60  # optional, default is 60 seconds
+end
+# Convert HTML to PDF
+pdf = PDFify.convert(
+  html: "<html><body><h1>Hello World!</h1></body></html>"
+)
+# Save to file
+File.binwrite("output.pdf", pdf)
+```
+## Usage
+### Basic Conversion
+```ruby
+# Simple HTML conversion
+pdf = PDFify.convert(html: "<h1>Hello!</h1>")
+File.binwrite("hello.pdf", pdf)
+```
+### Using Client Instance
+```ruby
+# Create a client instance
+client = PDFify::Client.new
+# Convert HTML
+pdf = client.convert(
+  html: "<html><body>Content here</body></html>"
+)
+```
+### Test/Sandbox Mode
+Use `test: true` or `sandbox: true` to generate PDFs without counting against your quota:
+```ruby
+pdf = PDFify.convert(
+  html: "<h1>Test</h1>",
+  test: true  # doesn't count against quota
+)
+```
+### Advanced Options
+```ruby
+pdf = PDFify.convert(
+  html: "<h1>Advanced</h1>",
+  profile: "docraptor",           # CSS profile compatibility
+  css: "body { color: red; }",    # Additional CSS
+  auto_compat: true,               # Auto-detect template engine
+  template_engine: "pdfshift"     # Specify engine explicitly
+)
+```
+### Error Handling
+```ruby
+begin
+  pdf = PDFify.convert(html: "<h1>Test</h1>")
+  File.binwrite("output.pdf", pdf)
+rescue PDFify::QuotaExceededError => e
+  puts "Quota exceeded: #{e.message}"
+rescue PDFify::ValidationError => e
+  puts "Invalid input: #{e.message}"
+rescue PDFify::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue PDFify::APIError => e
+  puts "API error: #{e.message}"
+end
+```
+### Available Error Classes
+- `PDFify::APIError` - Base error class
+- `PDFify::NetworkError` - Connection/network errors
+- `PDFify::AuthenticationError` - Invalid API key
+- `PDFify::ValidationError` - Invalid parameters (400)
+- `PDFify::QuotaExceededError` - Monthly quota exceeded (403)
+- `PDFify::ContentTooLargeError` - HTML content too large (413)
+- `PDFify::ServerError` - Server-side errors (500)
+- `PDFify::ConfigurationError` - Missing/invalid configuration
+## Configuration
+```ruby
+PDFify.configure do |config|
+  # Required: Your PDFify API key
+  config.api_key = "pfy_live_xxxxxxxxxx"
+  # Optional: API base URL (default: https://pdfify.example.com)
+  config.base_url = "https://api.pdfify.example.com"
+  # Optional: Request timeout in seconds (default: 60)
+  config.timeout = 60
+end
+```
+### Environment Variables
+You can also set the API key via environment variable:
+```ruby
+PDFify.configure do |config|
+  config.api_key = ENV['PDFIFY_API_KEY']
+end
+```
+## Integration with Rails
+### Initializer
+Create `config/initializers/pdfify.rb`:
+```ruby
+PDFify.configure do |config|
+  config.api_key = Rails.application.credentials.pdfify_api_key
+  # Or use ENV: config.api_key = ENV['PDFIFY_API_KEY']
+end
+```
+### Controller Example
+```ruby
+class ReportsController < ApplicationController
+  def download_pdf
+    html = render_to_string(template: "reports/invoice", layout: "pdf")
+    pdf = PDFify.convert(html: html)
+    send_data pdf,
+              type: "application/pdf",
+              disposition: "attachment",
+              filename: "invoice-#{@invoice.id}.pdf"
+  end
+end
+```
+### Service Object Example
+```ruby
+class InvoicePdfGenerator
+  def initialize(invoice)
+    @invoice = invoice
+  end
+  def generate
+    html = ApplicationController.render(
+      template: "invoices/show",
+      layout: "pdf",
+      assigns: { invoice: @invoice }
+    )
+    PDFify.convert(html: html)
+  rescue PDFify::APIError => e
+    Rails.logger.error "PDF generation failed: #{e.message}"
+    raise
+  end
+end
+# Usage:
+pdf = InvoicePdfGenerator.new(@invoice).generate
+```
+## Replacing DocRaptor
+If you're migrating from DocRaptor, here's a comparison:
+### DocRaptor:
+```ruby
+DocRaptor.configure do |config|
+  config.username = "YOUR_API_KEY"
+end
+docraptor = DocRaptor::DocApi.new
+pdf = docraptor.create_doc(
+  document_content: html,
+  document_type: "pdf",
+  test: true
+)
+```
+### PDFify:
+```ruby
+PDFify.configure do |config|
+  config.api_key = "YOUR_API_KEY"
+end
+pdf = PDFify.convert(
+  html: html,
+  test: true
+)
+```
+It's that simple! Just swap the gem and update your configuration.
+---
+## Development & Publishing Guide
+### Building the Gem Locally
+Follow these steps to build and test the gem:
+#### 1. Install Dependencies
+```bash
+cd pdfify-ruby
+bundle install
+```
+#### 2. Build the Gem
+```bash
+gem build pdfify.gemspec
+```
+This creates a `.gem` file like `pdfify-0.1.0.gem`.
+#### 3. Test Locally (Without Publishing)
+Install the gem locally to test it:
+```bash
+gem install ./pdfify-0.1.0.gem
+```
+Or in a Rails app's Gemfile:
+```ruby
+gem 'pdfify', path: '../pdfify-ruby'
+```
+Then run `bundle install`.
+#### 4. Test in IRB
+```bash
+irb
+```
+```ruby
+require 'pdfify'
+PDFify.configure do |config|
+  config.api_key = "pfy_test_xxxxxxxxxx"
+  config.base_url = "http://localhost:3000"  # Your local PDFify server
+end
+# Test it
+pdf = PDFify.convert(html: "<h1>Test</h1>", test: true)
+File.binwrite("test.pdf", pdf)
+```
+### Publishing to RubyGems.org
+#### Prerequisites
+1. Create a RubyGems.org account at https://rubygems.org
+2. Get your API key:
+   ```bash
+   curl -u YOUR_USERNAME https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
+   chmod 0600 ~/.gem/credentials
+   ```
+#### Step-by-Step Publishing
+##### 1. Prepare Your Gem
+Make sure all files are ready:
+- [ ] Update version in `lib/pdfify/version.rb`
+- [ ] Update gemspec with correct author/email/homepage
+- [ ] Create LICENSE.txt (MIT license recommended)
+- [ ] Create CHANGELOG.md documenting changes
+- [ ] Test thoroughly
+##### 2. Build the Gem
+```bash
+gem build pdfify.gemspec
+```
+##### 3. Push to RubyGems
+```bash
+gem push pdfify-0.1.0.gem
+```
+You'll see output like:
+```
+Pushing gem to https://rubygems.org...
+Successfully registered gem: pdfify (0.1.0)
+```
+##### 4. Verify
+Visit https://rubygems.org/gems/pdfify to see your published gem!
+##### 5. Install Anywhere
+Now anyone can install it:
+```bash
+gem install pdfify
+```
+Or in a Gemfile:
+```ruby
+gem 'pdfify', '~> 0.1.0'
+```
+### Publishing Updates
+When you need to release a new version:
+1. **Update version** in `lib/pdfify/version.rb`:
+   ```ruby
+   VERSION = "0.2.0"
+   ```
+2. **Update CHANGELOG.md** with changes
+3. **Build and push**:
+   ```bash
+   gem build pdfify.gemspec
+   gem push pdfify-0.2.0.gem
+   ```
+### Yanking a Version (Emergency)
+If you need to unpublish a broken version:
+```bash
+gem yank pdfify -v 0.1.0
+```
+### Best Practices
+- Use [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH
+  - MAJOR: Breaking changes
+  - MINOR: New features (backward compatible)
+  - PATCH: Bug fixes
+- Always test locally before publishing
+- Keep CHANGELOG.md updated
+- Tag releases in git: `git tag v0.1.0 && git push --tags`
+- Never publish with sensitive data (API keys, passwords)
+### Setting Up GitHub Repo (Optional but Recommended)
+```bash
+cd pdfify-ruby
+git init
+git add .
+git commit -m "Initial commit"
+git remote add origin https://github.com/yourusername/pdfify-ruby.git
+git push -u origin main
+```
+Then update gemspec with correct GitHub URLs.
+---
+## Testing
+Run the test suite (when tests are added):
+```bash
+bundle exec rspec
+```
+---
+## API Reference
+### `PDFify.configure { |config| ... }`
+Configure the global PDFify settings.
+**Parameters:**
+- `config.api_key` (String) - Your PDFify API key (required)
+- `config.base_url` (String) - API base URL (optional, default: https://pdfify.example.com)
+- `config.timeout` (Integer) - Request timeout in seconds (optional, default: 60)
+### `PDFify.convert(html:, **options)`
+Convert HTML to PDF.
+**Parameters:**
+- `html` (String) - HTML content to convert (required)
+- `test` (Boolean) - Enable test/sandbox mode (optional)
+- `sandbox` (Boolean) - Alias for `test` (optional)
+- `profile` (String) - CSS profile to use (optional)
+- `css` (String) - Additional CSS to inject (optional)
+- `auto_compat` (Boolean) - Enable auto-compatibility mode (optional)
+- `template_engine` (String) - Specify template engine (optional)
+**Returns:**
+- (String) Binary PDF data
+**Raises:**
+- `ArgumentError` if HTML is missing
+- `PDFify::ConfigurationError` if API key is not configured
+- `PDFify::APIError` and subclasses for API errors
+### `PDFify::Client.new(config = nil)`
+Create a new client instance.
+**Parameters:**
+- `config` (PDFify::Configuration) - Custom configuration (optional, uses global config if nil)
+**Returns:**
+- PDFify::Client instance
+---
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/pdfify-ruby.
+## Support
+- Documentation: https://pdfify.example.com/docs
+- Email: support@pdfify.example.com
+- GitHub Issues: https://github.com/yourusername/pdfify-ruby/issues

data/lib/pdfify/client.rb ADDED Viewed

@@ -0,0 +1,96 @@
+require 'httparty'
+module PDFify
+  class Client
+    include HTTParty
+    def initialize(config = nil)
+      @config = config || PDFify.configuration
+      @config.validate!
+      self.class.base_uri(@config.base_url)
+      self.class.default_timeout(@config.timeout)
+    end
+    # Generate a PDF from HTML
+    # @param html [String] The HTML content to convert
+    # @param options [Hash] Optional parameters
+    # @option options [Boolean] :test Enable test/sandbox mode (doesn't count against quota)
+    # @option options [Boolean] :sandbox Alias for :test
+    # @option options [String] :profile CSS profile to use
+    # @option options [String] :css Additional CSS to inject
+    # @option options [Boolean] :auto_compat Enable automatic compatibility mode detection
+    # @option options [String] :template_engine Specify template engine (docraptor, pdfshift, etc.)
+    # @return [String] Binary PDF data
+    def convert(html:, **options)
+      raise ArgumentError, "HTML content is required" if html.nil? || html.empty?
+      # Build request body
+      body = { html: html }
+      # Add optional parameters
+      body[:test] = options[:test] if options.key?(:test)
+      body[:sandbox] = options[:sandbox] if options.key?(:sandbox)
+      body[:profile] = options[:profile] if options.key?(:profile)
+      body[:css] = options[:css] if options.key?(:css)
+      body[:auto_compat] = options[:auto_compat] if options.key?(:auto_compat)
+      body[:template_engine] = options[:template_engine] if options.key?(:template_engine)
+      # Make API request
+      response = self.class.post(
+        "/api/v1/convert",
+        body: body,
+        headers: {
+          "Authorization" => "Bearer #{@config.api_key}",
+          "User-Agent" => "PDFify Ruby Gem v#{PDFify::VERSION}"
+        }
+      )
+      # Handle response
+      case response.code
+      when 200
+        response.body # Return binary PDF data
+      when 400
+        error = parse_error(response)
+        raise ValidationError, error
+      when 403
+        error = parse_error(response)
+        raise QuotaExceededError, error
+      when 413
+        error = parse_error(response)
+        raise ContentTooLargeError, error
+      when 401
+        raise AuthenticationError, "Invalid API key"
+      when 500
+        error = parse_error(response)
+        raise ServerError, error
+      else
+        raise APIError, "Unexpected response code: #{response.code}"
+      end
+    rescue HTTParty::Error, Timeout::Error, Errno::ECONNREFUSED => e
+      raise NetworkError, "Failed to connect to PDFify API: #{e.message}"
+    end
+    private
+    def parse_error(response)
+      return "Unknown error" unless response.body
+      begin
+        json = JSON.parse(response.body)
+        json["error"] || json["message"] || "Unknown error"
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+  # Custom error classes
+  class APIError < StandardError; end
+  class NetworkError < APIError; end
+  class AuthenticationError < APIError; end
+  class ValidationError < APIError; end
+  class QuotaExceededError < APIError; end
+  class ContentTooLargeError < APIError; end
+  class ServerError < APIError; end
+end

data/lib/pdfify/configuration.rb ADDED Viewed

@@ -0,0 +1,17 @@
+module PDFify
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+    def initialize
+      @api_key = nil
+      @base_url = "https://pdfify.example.com" # Default, can be overridden
+      @timeout = 60 # Default timeout in seconds
+    end
+    def validate!
+      raise ConfigurationError, "API key is required" if api_key.nil? || api_key.empty?
+    end
+  end
+  class ConfigurationError < StandardError; end
+end

data/lib/pdfify/version.rb ADDED Viewed

@@ -0,0 +1,3 @@
+module PDFify
+  VERSION = "0.1.0"
+end

data/lib/pdfify.rb ADDED Viewed

@@ -0,0 +1,38 @@
+require_relative 'pdfify/version'
+require_relative 'pdfify/configuration'
+require_relative 'pdfify/client'
+module PDFify
+  class << self
+    attr_writer :configuration
+    # Get or initialize configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    # Configure PDFify with a block
+    # @example
+    #   PDFify.configure do |config|
+    #     config.api_key = "pfy_live_xxx"
+    #     config.base_url = "https://pdfify.example.com"
+    #   end
+    def configure
+      yield(configuration)
+    end
+    # Reset configuration (useful for testing)
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+    # Convenience method to convert HTML without instantiating a client
+    # @param html [String] The HTML content to convert
+    # @param options [Hash] Optional parameters
+    # @return [String] Binary PDF data
+    def convert(html:, **options)
+      client = Client.new
+      client.convert(html: html, **options)
+    end
+  end
+end

metadata ADDED Viewed

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: pdfify-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- almokhtar
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A simple Ruby gem to convert HTML to PDF using the PDFify API. PDFify
+  is a DocRaptor alternative at 50% cheaper pricing.
+email:
+- hey@almokhtar.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/pdfify.rb
+- lib/pdfify/client.rb
+- lib/pdfify/configuration.rb
+- lib/pdfify/version.rb
+homepage: https://github.com/yourusername/pdfify-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yourusername/pdfify-ruby
+  source_code_uri: https://github.com/yourusername/pdfify-ruby
+  changelog_uri: https://github.com/yourusername/pdfify-ruby/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.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Ruby client for PDFify HTML-to-PDF API
+test_files: []