generatepdfs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 91475bc0ce1e8d67a9c11a62cd46fcbf5cdd5c17f43dd6aca4f246cac4eb7035
+  data.tar.gz: 814033fc9ab61491cccd1c39c6c2dda428d6c3d2d08e7103b1ab7728e4277a07
+SHA512:
+  metadata.gz: fccdcb2b89722e4faa7d10614085b01c6900c0da42c65c84571b7546a88a994349f429104e238547a752064919faaa18e209edb3ae343e064d1c9f7d710ef929
+  data.tar.gz: 9414cbc050cde53fd62dc694f33cb926ae3e4783f34c973c0bdcc3b24e5b1b898af5db795d3030515818d73ba4261b740fa4355e3d0be520361a811f2a27cfb3

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Change log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [1.0.0] - 2026-01-01
+
+* Support for uploading HTML/CSS/Images to generate PDF
+* Support for submitting a URL to generate PDF
+* Support for downloading and saving PDF from the API
+* Support for getting PDF data from PDF id
+* 100% Test coverage

data/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+Contributions and suggestion are **welcome** and will be fully **credited**.
+
+We accept contributions via Pull Requests on [Github](https://github.com/GeneratePDFs/ruby-sdk).
+
+## Pull Requests
+
+- **Follow Ruby style guide** - Use RuboCop to ensure code style consistency
+- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
+- **Document any change in behaviour** - Make sure the README / CHANGELOG and any other relevant documentation are kept up-to-date.
+- **Consider our release cycle** - We try to follow semver. Randomly breaking public APIs is not an option.
+- **Create topic branches** - Don't ask us to pull from your master branch.
+- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
+- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 GeneratePDFs
+
+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 @@
+# GeneratePDFs Ruby SDK
+
+Ruby SDK for the [GeneratePDFs.com](https://generatepdfs.com) API, your go-to place for HTML to PDF.
+
+Upload your HTML files, along with any CSS files and images to generate a PDF. Alternatively provide a URL to generate a PDF from it's contents.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'generatepdfs'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install generatepdfs
+```
+
+## Get your API Token
+
+Sign up for an account on [GeneratePDFs.com](https://generatepdfs.com) and head to the API Tokens section and create a new token.
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require 'generatepdfs'
+
+client = GeneratePDFs::GeneratePDFs.connect('YOUR_API_TOKEN')
+```
+
+### Generate PDF from HTML File
+
+```ruby
+require 'generatepdfs'
+
+# Simple HTML file
+pdf = client.generate_from_html('/path/to/file.html')
+
+# HTML file with CSS
+pdf = client.generate_from_html(
+  '/path/to/file.html',
+  '/path/to/file.css'
+)
+
+# HTML file with CSS and images
+pdf = client.generate_from_html(
+  '/path/to/file.html',
+  '/path/to/file.css',
+  [
+    {
+      name: 'logo.png',
+      path: '/path/to/logo.png',
+      mime_type: 'image/png' # Optional, will be auto-detected
+    },
+    {
+      name: 'photo.jpg',
+      path: '/path/to/photo.jpg'
+    }
+  ]
+)
+```
+
+### Generate PDF from URL
+
+```ruby
+pdf = client.generate_from_url('https://example.com')
+```
+
+### Get PDF by ID
+
+```ruby
+# Retrieve a PDF by its ID
+pdf = client.get_pdf(123)
+```
+
+### Working with PDF Objects
+
+The SDK returns `Pdf` objects that provide easy access to PDF information and downloading:
+
+```ruby
+# Access PDF properties
+pdf_id = pdf.id
+pdf_name = pdf.name
+status = pdf.status
+download_url = pdf.download_url
+created_at = pdf.created_at
+
+# Check if PDF is ready
+if pdf.ready?
+  # Download PDF content as string
+  pdf_content = pdf.download
+  
+  # Or save directly to file
+  pdf.download_to_file('/path/to/save/output.pdf')
+end
+
+# Refresh PDF data from the API (useful for checking status updates)
+refreshed_pdf = pdf.refresh
+if refreshed_pdf.ready?
+  pdf_content = refreshed_pdf.download
+end
+```
+
+### Client Methods
+
+- `generate_from_html(html_path, css_path = nil, images = [])` - Generate a PDF from HTML file(s)
+- `generate_from_url(url)` - Generate a PDF from a URL
+- `get_pdf(id)` - Retrieve a PDF by its ID
+- `download_pdf(download_url)` - Download PDF binary content from a download URL
+
+### PDF Object Methods
+
+- `id` - Get the PDF ID
+- `name` - Get the PDF filename
+- `status` - Get the current status (pending, processing, completed, failed)
+- `download_url` - Get the download URL
+- `created_at` - Get the creation date
+- `ready?` - Check if the PDF is ready for download
+- `download` - Download and return PDF binary content
+- `download_to_file(file_path)` - Download and save PDF to a file
+- `refresh` - Refresh PDF data from the API and return a new Pdf instance with updated information
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Faraday 2.0 or higher
+- MIME::Types 3.0 or higher
+
+## Testing
+
+To run the test suite, execute:
+
+```bash
+bundle exec rspec
+```
+
+To run tests with coverage:
+
+```bash
+bundle exec rspec --format documentation
+```
+
+## Contributing
+
+Contributions and suggestions are **welcome** and will be fully **credited**.
+
+We accept contributions via Pull Requests on [GitHub](https://github.com/GeneratePDFs/ruby-sdk).
+
+### Pull Requests
+
+- **Follow Ruby style guide** - Use RuboCop to ensure code style consistency
+- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
+- **Document any change in behaviour** - Make sure the README / CHANGELOG and any other relevant documentation are kept up-to-date.
+- **Consider our release cycle** - We try to follow semver. Randomly breaking public APIs is not an option.
+- **Create topic branches** - Don't ask us to pull from your master branch.
+- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
+- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

data/lib/generatepdfs/exceptions/invalid_argument_exception.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GeneratePDFs
+  class InvalidArgumentException < StandardError
+  end
+end

data/lib/generatepdfs/exceptions/runtime_exception.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GeneratePDFs
+  class RuntimeException < StandardError
+  end
+end

data/lib/generatepdfs/generate_pdfs.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'base64'
+require 'json'
+require 'uri'
+require 'mime/types'
+require_relative 'pdf'
+require_relative 'exceptions/invalid_argument_exception'
+require_relative 'exceptions/runtime_exception'
+
+module GeneratePDFs
+  # Main client class for interacting with the GeneratePDFs API
+  class GeneratePDFs
+    BASE_URL = 'https://api.generatepdfs.com'
+
+    # Create a new GeneratePDFs instance with the provided API token.
+    #
+    # @param api_token [String] The API token for authentication
+    # @return [GeneratePDFs] A new GeneratePDFs instance
+    def self.connect(api_token)
+      new(api_token)
+    end
+
+    # Initialize a new GeneratePDFs client
+    #
+    # @param api_token [String] The API token for authentication
+    def initialize(api_token)
+      @api_token = api_token
+      @client = Faraday.new(
+        url: BASE_URL,
+        headers: {
+          'Content-Type' => 'application/json'
+        }
+      ) do |conn|
+        conn.request :json
+        conn.response :json
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Generate a PDF from HTML file(s) with optional CSS and images.
+    #
+    # @param html_path [String] Path to the HTML file
+    # @param css_path [String, nil] Optional path to the CSS file
+    # @param images [Array<Hash>] Optional array of image files with keys: :name, :path, :mime_type
+    # @return [Pdf] PDF object containing PDF information
+    # @raise [InvalidArgumentException] If files are invalid
+    def generate_from_html(html_path, css_path = nil, images = [])
+      unless File.exist?(html_path) && File.readable?(html_path)
+        raise InvalidArgumentException, "HTML file not found or not readable: #{html_path}"
+      end
+
+      html_content = Base64.strict_encode64(File.read(html_path))
+
+      data = {
+        html: html_content
+      }
+
+      if css_path
+        unless File.exist?(css_path) && File.readable?(css_path)
+          raise InvalidArgumentException, "CSS file not found or not readable: #{css_path}"
+        end
+
+        data[:css] = Base64.strict_encode64(File.read(css_path))
+      end
+
+      data[:images] = process_images(images) unless images.empty?
+
+      response = make_request('/pdfs/generate', data)
+
+      data_hash = response['data'] || response[:data]
+      unless data_hash
+        raise InvalidArgumentException, 'Invalid API response: missing data'
+      end
+
+      Pdf.from_hash(data_hash, self)
+    end
+
+    # Generate a PDF from a URL.
+    #
+    # @param url [String] The URL to convert to PDF
+    # @return [Pdf] PDF object containing PDF information
+    # @raise [InvalidArgumentException] If URL is invalid
+    def generate_from_url(url)
+      begin
+        uri = URI.parse(url)
+        raise InvalidArgumentException, "Invalid URL: #{url}" unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+      rescue URI::InvalidURIError
+        raise InvalidArgumentException, "Invalid URL: #{url}"
+      end
+
+      data = {
+        url: url
+      }
+
+      response = make_request('/pdfs/generate', data)
+
+      data_hash = response['data'] || response[:data]
+      unless data_hash
+        raise InvalidArgumentException, 'Invalid API response: missing data'
+      end
+
+      Pdf.from_hash(data_hash, self)
+    end
+
+    # Get a PDF by its ID.
+    #
+    # @param id [Integer] The PDF ID
+    # @return [Pdf] PDF object containing PDF information
+    # @raise [InvalidArgumentException] If ID is invalid
+    def get_pdf(id)
+      if id <= 0
+        raise InvalidArgumentException, "Invalid PDF ID: #{id}"
+      end
+
+      response = make_get_request("/pdfs/#{id}")
+
+      data_hash = response['data'] || response[:data]
+      unless data_hash
+        raise InvalidArgumentException, 'Invalid API response: missing data'
+      end
+
+      Pdf.from_hash(data_hash, self)
+    end
+
+    # Download a PDF from the API.
+    #
+    # @param download_url [String] The download URL for the PDF
+    # @return [String] PDF binary content
+    def download_pdf(download_url)
+      response = @client.get(download_url) do |req|
+        req.headers['Authorization'] = "Bearer #{@api_token}"
+      end
+
+      raise RuntimeException, "Failed to download PDF: #{response.status}" unless response.success?
+
+      response.body
+    end
+
+    private
+
+    # Process image files and return formatted array for API.
+    #
+    # @param images [Array<Hash>] Array of image inputs with keys: :name, :path, :mime_type
+    # @return [Array<Hash>] Array of processed images
+    def process_images(images)
+      processed = []
+
+      images.each do |image|
+        next unless image[:path] && image[:name]
+
+        path = image[:path]
+        name = image[:name]
+
+        next unless File.exist?(path) && File.readable?(path)
+
+        content = Base64.strict_encode64(File.read(path))
+
+        # Detect mime type if not provided
+        mime_type = image[:mime_type] || detect_mime_type(path)
+
+        processed << {
+          name: name,
+          content: content,
+          mime_type: mime_type
+        }
+      end
+
+      processed
+    end
+
+    # Detect MIME type of a file.
+    #
+    # @param file_path [String] Path to the file
+    # @return [String] MIME type
+    def detect_mime_type(file_path)
+      mime_type = MIME::Types.type_for(file_path).first
+      return mime_type.to_s if mime_type
+
+      # Fallback to extension-based detection
+      extension = File.extname(file_path).downcase.delete_prefix('.')
+      mime_types = {
+        'jpg' => 'image/jpeg',
+        'jpeg' => 'image/jpeg',
+        'png' => 'image/png',
+        'gif' => 'image/gif',
+        'webp' => 'image/webp',
+        'svg' => 'image/svg+xml'
+      }
+
+      mime_types[extension] || 'application/octet-stream'
+    end
+
+    # Make an HTTP POST request to the API.
+    #
+    # @param endpoint [String] API endpoint
+    # @param data [Hash] Request data
+    # @return [Hash] Decoded JSON response
+    def make_request(endpoint, data)
+      response = @client.post(endpoint) do |req|
+        req.headers['Authorization'] = "Bearer #{@api_token}"
+        req.body = data.to_json
+      end
+
+      unless response.success?
+        error_msg = response.reason_phrase || response.status.to_s
+        raise RuntimeException, "API request failed: #{response.status} #{error_msg}"
+      end
+
+      response.body.is_a?(Hash) ? response.body : JSON.parse(response.body)
+    end
+
+    # Make an HTTP GET request to the API.
+    #
+    # @param endpoint [String] API endpoint
+    # @return [Hash] Decoded JSON response
+    def make_get_request(endpoint)
+      response = @client.get(endpoint) do |req|
+        req.headers['Authorization'] = "Bearer #{@api_token}"
+      end
+
+      unless response.success?
+        error_msg = response.reason_phrase || response.status.to_s
+        raise RuntimeException, "API request failed: #{response.status} #{error_msg}"
+      end
+
+      response.body.is_a?(Hash) ? response.body : JSON.parse(response.body)
+    end
+  end
+end

data/lib/generatepdfs/pdf.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative 'exceptions/invalid_argument_exception'
+require_relative 'exceptions/runtime_exception'
+
+module GeneratePDFs
+  # PDF object representing a PDF document from the API
+  class Pdf
+    attr_reader :id, :name, :status, :download_url, :created_at
+
+    # Create a Pdf instance from API response data.
+    #
+    # @param data [Hash] API response data with keys: id, name, status, download_url, created_at
+    # @param client [GeneratePDFs] The GeneratePDFs client instance
+    # @return [Pdf] A new Pdf instance
+    # @raise [InvalidArgumentException] If data structure is invalid
+    def self.from_hash(data, client)
+      # Normalize keys to symbols for easier access
+      normalized_data = data.transform_keys(&:to_sym)
+
+      required_keys = %i[id name status download_url created_at]
+      missing_keys = required_keys - normalized_data.keys
+
+      unless missing_keys.empty?
+        raise InvalidArgumentException, 'Invalid PDF data structure'
+      end
+
+      # Parse the created_at date
+      begin
+        created_at = Time.parse(normalized_data[:created_at].to_s)
+      rescue ArgumentError
+        raise InvalidArgumentException, "Invalid created_at format: #{normalized_data[:created_at]}"
+      end
+
+      new(
+        normalized_data[:id].to_i,
+        normalized_data[:name].to_s,
+        normalized_data[:status].to_s,
+        normalized_data[:download_url].to_s,
+        created_at,
+        client
+      )
+    end
+
+    # Initialize a new Pdf instance
+    #
+    # @param id [Integer] PDF ID
+    # @param name [String] PDF name
+    # @param status [String] PDF status
+    # @param download_url [String] Download URL
+    # @param created_at [Time] Creation date
+    # @param client [GeneratePDFs] The GeneratePDFs client instance
+    def initialize(id, name, status, download_url, created_at, client)
+      @id = id
+      @name = name
+      @status = status
+      @download_url = download_url
+      @created_at = created_at
+      @client = client
+    end
+
+    # Check if the PDF is ready for download.
+    #
+    # @return [Boolean] True if PDF is ready
+    def ready?
+      @status == 'completed'
+    end
+
+    # Download the PDF content.
+    #
+    # @return [String] PDF binary content
+    # @raise [RuntimeException] If the PDF is not ready or download fails
+    def download
+      unless ready?
+        raise RuntimeException, "PDF is not ready yet. Current status: #{@status}"
+      end
+
+      @client.download_pdf(@download_url)
+    end
+
+    # Download the PDF and save it to a file.
+    #
+    # @param file_path [String] Path where to save the PDF file
+    # @return [Boolean] True on success
+    # @raise [RuntimeException] If the PDF is not ready or download fails
+    def download_to_file(file_path)
+      content = download
+
+      File.binwrite(file_path, content)
+      true
+    rescue StandardError => e
+      raise RuntimeException, "Failed to write PDF to file: #{file_path} - #{e.message}"
+    end
+
+    # Refresh the PDF data from the API.
+    #
+    # @return [Pdf] A new Pdf instance with updated data
+    def refresh
+      @client.get_pdf(@id)
+    end
+  end
+end

data/lib/generatepdfs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GeneratePDFs
+  VERSION = '1.0.0'
+end

data/lib/generatepdfs.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'generatepdfs/version'
+require_relative 'generatepdfs/generate_pdfs'
+require_relative 'generatepdfs/pdf'
+require_relative 'generatepdfs/exceptions/invalid_argument_exception'
+require_relative 'generatepdfs/exceptions/runtime_exception'
+
+module GeneratePDFs
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: generatepdfs
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- GeneratePDFs
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+description: Ruby SDK for the GeneratePDFs.com API, your go-to place for HTML to PDF.
+email:
+- info@generatepdfs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- lib/generatepdfs.rb
+- lib/generatepdfs/exceptions/invalid_argument_exception.rb
+- lib/generatepdfs/exceptions/runtime_exception.rb
+- lib/generatepdfs/generate_pdfs.rb
+- lib/generatepdfs/pdf.rb
+- lib/generatepdfs/version.rb
+homepage: https://github.com/GeneratePDFs/ruby-sdk
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby SDK for GeneratePDFs.com API
+test_files: []