feat: implement complete Ruby SDK v0.1.0

- Full Ruby 3.1+ SDK with keyword arguments and block-based configuration
- API version support: v1 (sync binary), v2 (async Job)
- Conversion API: url_to_pdf, url_to_image, html_to_pdf, html_to_image,
  template_to_pdf, template_to_image, docx_to_pdf, docx_to_html,
  pdf_to_docx, merge_pdfs
- Data Management API: list/get jobs, assets, storage; add/delete storage;
  get_account, get_status, list/get templates
- Utility: wait_for_job (polling), download_job_result, HtmlUtil.encode_html
- HTTP transport with retry (exponential backoff+jitter), multipart upload,
  redirect following for presigned S3 URLs
- Type system: frozen constant modules, OptionBase DSL with field declarations,
  response classes with from_hash deserialization
- Error hierarchy: Error < {ConfigError, ValidationError, NetworkError,
  TimeoutError, ApiError < {AuthError, RateLimitError}}
- YARD doc comments on all public classes and methods
- RSpec test suite: >97% coverage across unit and integration specs
- RuboCop linting, .yardopts for YARD generation
- Comprehensive README with examples for all methods
- CHANGELOG for v0.1.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: elucidsoft

.rubocop.yml

@@ -17,9 +17,27 @@ Metrics/BlockLength:
     - "spec/**/*"
 
 Metrics/MethodLength:
+  Max: 15
+  CountAsOne:
+    - hash
+    - heredoc
   Exclude:
     - "spec/**/*"
 
 Metrics/ModuleLength:
+  Max: 110
   Exclude:
     - "spec/**/*"
+
+Metrics/ClassLength:
+  Exclude:
+    - "lib/cloudlayerio/http/transport.rb"
+
+# API method names match the CloudLayer SDK convention across all languages
+Naming/AccessorMethodName:
+  Exclude:
+    - "lib/cloudlayerio/api/**/*"
+
+Naming/PredicateMethod:
+  Exclude:
+    - "lib/cloudlayerio/api/**/*"

CHANGELOG.md

@@ -5,4 +5,42 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.1.0] - 2026-03-17
+
+### Added
+
+- Client configuration with keyword arguments and block-based setup
+- API version support (v1 sync binary, v2 async Job)
+- **Conversion methods:**
+  - `url_to_pdf` / `url_to_image` — convert URLs to PDF or image
+  - `html_to_pdf` / `html_to_image` — convert Base64-encoded HTML
+  - `template_to_pdf` / `template_to_image` — render server-side templates
+  - `docx_to_pdf` / `docx_to_html` — convert DOCX documents (multipart upload)
+  - `pdf_to_docx` — convert PDF to DOCX (multipart upload)
+  - `merge_pdfs` — merge multiple PDFs from URLs
+- **Data management:**
+  - `list_jobs` / `get_job` — query conversion jobs
+  - `list_assets` / `get_asset` — query generated assets
+  - `list_storage` / `get_storage` / `add_storage` / `delete_storage` — manage S3 storage configs
+  - `get_account` — retrieve account information
+  - `get_status` — API health check
+  - `list_templates` / `get_template` — browse public template gallery
+- **Utility methods:**
+  - `wait_for_job` — poll for job completion with configurable interval and timeout
+  - `download_job_result` — download binary output from completed jobs
+  - `CloudLayerio::Util::HtmlUtil.encode_html` — Base64-encode HTML for the API
+- **HTTP transport:**
+  - Retry logic with exponential backoff and jitter (429, 500-504)
+  - Multipart file upload support
+  - Redirect following for presigned S3 URLs
+  - Configurable timeout, max retries, custom headers
+- **Error handling:**
+  - `AuthError` (401/403), `RateLimitError` (429 with retry_after), `ApiError` (4xx/5xx)
+  - `TimeoutError`, `NetworkError`, `ValidationError`, `ConfigError`
+- **Type system:**
+  - Frozen constant modules (PdfFormat, ImageType, JobStatus, JobType, WaitUntilOption)
+  - Option classes with keyword arguments and camelCase JSON serialization
+  - Response classes with `from_hash` deserialization
+  - `NOT_SET` sentinel for three-state `emulate_media_type`
+- Client-side validation for all endpoints
+- RSpec test suite with >97% coverage

README.md

@@ -1,29 +1,306 @@
 # cloudlayerio
 
-Official Ruby SDK for the [CloudLayer.io](https://cloudlayer.io) document generation API.
+Official Ruby SDK for the [cloudlayer.io](https://cloudlayer.io) document generation API.
 
-## Status: In Development
+[![Gem Version](https://badge.fury.io/rb/cloudlayerio.svg)](https://rubygems.org/gems/cloudlayerio)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-This SDK is currently under development. See the [CHANGELOG](CHANGELOG.md) for progress.
+Convert HTML, URLs, and templates to PDF and images. Supports file conversions (DOCX to PDF, PDF to DOCX), PDF merging, and a visual template editor.
+
+## Requirements
+
+- Ruby >= 3.1
+- One runtime dependency: `base64` gem (bundled with Ruby; extracted to a separate gem in Ruby 3.4+)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
-gem "cloudlayerio"
+gem "cloudlayerio", "~> 0.1"
 ```
 
-And then execute:
+Then run `bundle install`. Or install directly:
 
 ```bash
-bundle install
+gem install cloudlayerio
 ```
 
-Or install it yourself as:
+## Quick Start
+
+```ruby
+require "cloudlayerio"
+
+# v2 (async) — returns a Job object
+client = CloudLayerio::Client.new(api_key: "your-api-key", api_version: :v2)
+result = client.url_to_pdf(url: "https://example.com", async: true, storage: true)
+job = client.wait_for_job(result.job.id)
+data = client.download_job_result(job)
+File.binwrite("output.pdf", data)
+
+# v1 (sync) — returns binary data directly
+client = CloudLayerio::Client.new(api_key: "your-api-key", api_version: :v1)
+result = client.url_to_pdf(url: "https://example.com")
+File.binwrite("output.pdf", result.bytes)
+```
+
+## Configuration
+
+```ruby
+client = CloudLayerio::Client.new do |config|
+  config.api_key = "your-api-key"     # Required
+  config.api_version = :v2             # Required — :v1 or :v2
+  config.base_url = "https://api.cloudlayer.io"  # Default
+  config.timeout = 30                  # Seconds, default 30
+  config.max_retries = 2              # 0-5, default 2
+  config.user_agent = "my-app/1.0"    # Custom user agent
+  config.headers = { "X-Custom" => "value" }  # Extra headers
+end
+```
+
+## Conversion Methods
+
+### URL to PDF
+
+```ruby
+result = client.url_to_pdf(
+  url: "https://example.com",
+  format: "a4",
+  print_background: true,
+  margin: CloudLayerio::Options::Margin.new(top: "10px", bottom: "10px")
+)
+```
+
+### URL to Image
+
+```ruby
+result = client.url_to_image(
+  url: "https://example.com",
+  image_type: "png",
+  quality: 90
+)
+```
+
+### HTML to PDF
+
+```ruby
+html = CloudLayerio::Util::HtmlUtil.encode_html("<h1>Hello World</h1><p>Generated with cloudlayer.io</p>")
+result = client.html_to_pdf(html: html, format: "letter")
+```
+
+### HTML to Image
+
+```ruby
+html = CloudLayerio::Util::HtmlUtil.encode_html("<div style='padding:20px'>Screenshot</div>")
+result = client.html_to_image(html: html, image_type: "png")
+```
+
+### Template to PDF
+
+```ruby
+result = client.template_to_pdf(
+  template_id: "your-template-id",
+  data: { name: "John Doe", invoice_number: "INV-001" }
+)
+```
+
+### Template to Image
+
+```ruby
+result = client.template_to_image(
+  template_id: "your-template-id",
+  data: { title: "Certificate of Completion" },
+  image_type: "png"
+)
+```
+
+### DOCX to PDF
+
+```ruby
+result = client.docx_to_pdf(file: "/path/to/document.docx")
+```
+
+### DOCX to HTML
+
+```ruby
+result = client.docx_to_html(file: "/path/to/document.docx")
+```
+
+### PDF to DOCX
+
+```ruby
+result = client.pdf_to_docx(file: "/path/to/document.pdf")
+```
+
+### Merge PDFs
+
+```ruby
+result = client.merge_pdfs(
+  batch: CloudLayerio::Options::Batch.new(urls: [
+    "https://example.com/page1.pdf",
+    "https://example.com/page2.pdf"
+  ])
+)
+```
+
+## Working with v2 Results
+
+v2 API returns a Job object. Poll for completion, then download:
+
+```ruby
+client = CloudLayerio::Client.new(api_key: "your-key", api_version: :v2)
+
+# Start conversion
+result = client.url_to_pdf(url: "https://example.com", async: true, storage: true)
+puts "Job created: #{result.job.id}"
+
+# Wait for completion (polls every 5 seconds, up to 5 minutes)
+job = client.wait_for_job(result.job.id)
+puts "Job completed: #{job.status}"
+
+# Download the result
+pdf_data = client.download_job_result(job)
+File.binwrite("output.pdf", pdf_data)
+```
+
+## Data Management
+
+### Jobs
+
+```ruby
+jobs = client.list_jobs          # Up to 10 most recent
+job = client.get_job("job-id")
+```
+
+### Assets
+
+```ruby
+assets = client.list_assets      # Up to 10 most recent
+asset = client.get_asset("asset-id")
+```
+
+### Storage
+
+```ruby
+storages = client.list_storage
+detail = client.get_storage("storage-id")
+
+# Create storage configuration
+resp = client.add_storage(
+  title: "My S3",
+  region: "us-east-1",
+  access_key_id: "AKIA...",
+  secret_access_key: "...",
+  bucket: "my-bucket"
+)
+
+# Delete storage configuration
+client.delete_storage("storage-id")
+```
+
+### Account
+
+```ruby
+account = client.get_account
+puts "Email: #{account.email}, Calls: #{account.calls}/#{account.calls_limit}"
+
+status = client.get_status
+puts status.status  # "ok "
+```
+
+### Templates
+
+```ruby
+templates = client.list_templates(type: "pdf", category: "invoice")
+template = client.get_template("template-id")
+```
+
+## Error Handling
+
+```ruby
+begin
+  result = client.url_to_pdf(url: "https://example.com")
+rescue CloudLayerio::AuthError => e
+  puts "Authentication failed: #{e.message} (#{e.status_code})"
+rescue CloudLayerio::RateLimitError => e
+  puts "Rate limited, retry after #{e.retry_after} seconds"
+rescue CloudLayerio::ApiError => e
+  puts "API error #{e.status_code}: #{e.message}"
+rescue CloudLayerio::TimeoutError => e
+  puts "Request timed out: #{e.message}"
+rescue CloudLayerio::NetworkError => e
+  puts "Connection failed: #{e.message}"
+rescue CloudLayerio::ValidationError => e
+  puts "Invalid input: #{e.message}"
+rescue CloudLayerio::ConfigError => e
+  puts "Bad configuration: #{e.message}"
+end
+```
+
+**Error hierarchy:**
+
+```
+CloudLayerio::Error < StandardError
+├── ConfigError          (invalid client config)
+├── ValidationError      (client-side input validation)
+├── NetworkError         (connection/DNS failure)
+├── TimeoutError         (request timeout)
+└── ApiError             (HTTP 4xx/5xx)
+    ├── AuthError        (401/403)
+    └── RateLimitError   (429, includes retry_after)
+```
+
+## Advanced Options
+
+### Viewport and Margins
+
+```ruby
+result = client.url_to_pdf(
+  url: "https://example.com",
+  view_port: CloudLayerio::Options::Viewport.new(width: 1920, height: 1080, is_mobile: false),
+  margin: CloudLayerio::Options::Margin.new(top: "1in", bottom: "1in", left: "0.5in", right: "0.5in")
+)
+```
+
+### Cookies and Authentication
+
+```ruby
+result = client.url_to_pdf(
+  url: "https://example.com/dashboard",
+  authentication: CloudLayerio::Options::Authentication.new(username: "user", password: "pass"),
+  cookies: [CloudLayerio::Options::Cookie.new(name: "session", value: "abc123", http_only: true)]
+)
+```
+
+### Async with Storage and Webhooks
+
+```ruby
+result = client.url_to_pdf(
+  url: "https://example.com",
+  async: true,
+  storage: true,
+  webhook: "https://your-app.com/webhook"
+)
+```
+
+### Batch Processing
+
+```ruby
+result = client.url_to_pdf(
+  batch: CloudLayerio::Options::Batch.new(urls: [
+    "https://example.com/page1",
+    "https://example.com/page2"
+  ])
+)
+```
+
+## API Reference
+
+Generate YARD documentation locally:
 
 ```bash
-gem install cloudlayerio
+bundle exec yard doc
+open doc/index.html
 ```
 
 ## License