api2convert 10.2.0 → 10.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d6b5c540037362377c06e4096518c623017c17882b39233f932f73f0b70d14
-  data.tar.gz: 37b28638fbef0fd35e3eff63abb8557fd27c4400a4c4e63bab170dbf86d0fd8e
+  metadata.gz: 39056074d7f58decce593b6b8baae8d93bf51f1b5e8bc28d4f803febccedd74a
+  data.tar.gz: 268f0497c655e8cbe40aef88b56642b803f7def33d6dbf06495979977d94967e
 SHA512:
-  metadata.gz: 83f600ae36bd429c61df404004a744b2cb51dad8aedab4c739c79ed83b8c95d77542c5162d0c356a84cb7515d369457f6264c92c1d03c898a84c74768148444c
-  data.tar.gz: 63031c428a7bb3ea8e976ac2861c38dc27b83585ab41c0927ad24660a3c1d9a2aee10724b6b9b743ea947019e026f941ab84272fefb472b88a0fbd5710c3a4e0
+  metadata.gz: 107965e469189bae258af1ec97409a89db7a0b1b898295a1322b0701d0c49e2544850ca439caa3459d46637eff51e1b4cc926f5d21dfdea5aa8235596a353242
+  data.tar.gz: 446402026e834fcb47a077a64db9f5cee4442e07056700b5770bfe98332c7560799228d25fb88a633f919c2fdb12965fba1423fd4b24a2e208476ad8ad8d258a

data/README.md

@@ -150,6 +150,44 @@ Live conformance tests hit the real API and are skipped unless a key is present:
 $ API2CONVERT_API_KEY=<your key> bundle exec rake spec:live
 ```
 
+Each guide has a runnable, self-contained example under [`examples/`](examples/),
+and the [live conformance suite](spec/live/conformance_spec.rb) mirrors every one
+of them (same operation, plus assertions) so a published version is always
+verified end to end. It runs automatically against the real API on every release
+tag (see `.github/workflows/live-conformance.yml`).
+
+| # | Example | What it shows |
+|---|---------|---------------|
+| 1 | [`quickstart.rb`](examples/quickstart.rb) | Convert a remote URL, fetch the job, download the output |
+| 2 | [`convert_files.rb`](examples/convert_files.rb) | Browse the conversions catalog, then convert |
+| 3 | [`uploading_files.rb`](examples/uploading_files.rb) | One-call upload + convert of a local file |
+| 4 | [`job_lifecycle.rb`](examples/job_lifecycle.rb) | Drive create → add input → start → wait → outputs by hand |
+| 5 | [`add_watermark.rb`](examples/add_watermark.rb) | Stamp a PDF with an image (two remote inputs) |
+| 6 | [`create_thumbnails.rb`](examples/create_thumbnails.rb) | Render a thumbnail of the first PDF page |
+| 7 | [`compress_files.rb`](examples/compress_files.rb) | Compress an image with the compress operation |
+| 8 | [`create_archives.rb`](examples/create_archives.rb) | Bundle remote files into a ZIP |
+| 9 | [`create_hashes.rb`](examples/create_hashes.rb) | Compute a file's SHA-256 checksum |
+| 10 | [`extract_assets.rb`](examples/extract_assets.rb) | Extract embedded assets from a document |
+| 11 | [`file_analysis.rb`](examples/file_analysis.rb) | Extract file metadata as JSON |
+| 12 | [`compare_files.rb`](examples/compare_files.rb) | Diff two images with compare-image |
+| 13 | [`capture_website.rb`](examples/capture_website.rb) | Screenshot a page with the screenshot engine |
+| 14 | [`audio_operations.rb`](examples/audio_operations.rb) | Re-encode audio to AAC |
+| 15 | [`image_operations.rb`](examples/image_operations.rb) | Resize an image |
+| 16 | [`webhooks.rb`](examples/webhooks.rb) | Start an async job with a callback URL |
+| 17 | [`presets.rb`](examples/presets.rb) | List saved conversion presets |
+| 18 | [`statistics.rb`](examples/statistics.rb) | Read monthly API usage |
+| 19 | [`rate-limits.rb`](examples/rate-limits.rb) | Inspect the account's contracts |
+| 20 | [`authentication.rb`](examples/authentication.rb) | Verify the API key by listing jobs |
+
+A companion [`webhook.rb`](examples/webhook.rb) is a tiny Rack receiver that
+verifies the callback signature — the other side of example 16.
+
+Run any example with your key in the environment:
+
+```console
+$ API2CONVERT_API_KEY=<your key> ruby -Ilib examples/quickstart.rb
+```
+
 If your machine's Ruby is older than the gem targets, run the guardrail on a
 supported Ruby with the bundled `Dockerfile`:
 

data/docs/CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to the API2Convert Ruby SDK are documented here. The five
 official SDKs (PHP, Python, Java, Node.js, Ruby) version together against the
 shared [`SDK_CONTRACT.md`](SDK_CONTRACT.md).
 
-## [Unreleased]
+## [10.2.1] - 2026-07-08
 
-- Initial development; not yet publicly released.
+- Lock-step version bump to keep all API2Convert SDKs on 10.2.1. No library changes since 10.2.0
+  (the redirect / download-password hardening already shipped); added a runnable example per
+  documented guide and expanded the live-conformance suite to seven canonical scenarios.

data/examples/add_watermark.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Add a Watermark — stamp a PDF with an image using two remote inputs.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/add_watermark.rb
+
+require "api2convert"
+
+PDF = "https://example-files.online-convert.com/document/pdf/example.pdf"
+PNG = "https://example-files.online-convert.com/raster%20image/png/example.png"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# Create a job with two inputs (the document and the stamp image) and start it.
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      { "type" => "remote", "source" => PDF },
+      { "type" => "remote", "source" => PNG }
+    ],
+    "conversion" => [
+      {
+        "category" => "document",
+        "target" => "pdf",
+        "options" => { "stamp" => true, "alignment" => "center" }
+      }
+    ]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+outputs = client.jobs.outputs(job.id)
+outputs.each { |output| puts output.uri }

data/examples/audio_operations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Audio Operations — re-encode a WAV to AAC with explicit codec settings.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/audio_operations.rb
+
+require "api2convert"
+
+WAV = "https://example-files.online-convert.com/audio/wav/example.wav"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  WAV,
+  "aac",
+  { "audio_codec" => "aac", "audio_bitrate" => 192, "channels" => "stereo", "frequency" => 44_100 },
+  category: "audio"
+)
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/authentication.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Authentication — verify your API key by listing your jobs.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/authentication.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# A successful, authenticated call returns your jobs (empty on a fresh account).
+jobs = client.jobs.list
+puts "authenticated: #{jobs.length} job(s) visible"

data/examples/capture_website.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Capture a Website — screenshot a page with the screenshot engine.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/capture_website.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      {
+        "type" => "remote",
+        "source" => "https://www.online-convert.com",
+        "engine" => "screenshot",
+        "options" => { "screen_width" => 1280, "screen_height" => 1024, "device_scale_factor" => 1 }
+      }
+    ],
+    "conversion" => [{ "category" => "image", "target" => "png" }]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+client.jobs.outputs(job.id).each { |output| puts output.uri }

data/examples/compare_files.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Compare Files — diff two images with the compare-image operation.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/compare_files.rb
+
+require "api2convert"
+
+JPG_SMALL = "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      { "type" => "remote", "source" => JPG_SMALL },
+      { "type" => "remote", "source" => JPG }
+    ],
+    "conversion" => [
+      {
+        "category" => "operation",
+        "target" => "compare-image",
+        "options" => { "method" => "ssim", "threshold" => 5, "diff_color" => "red" }
+      }
+    ]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+client.jobs.outputs(job.id).each { |output| puts output.uri }

data/examples/compress_files.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Compress Files — shrink an image with the compress operation.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/compress_files.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  JPG, "compress", { "compression_level" => "high" }, category: "operation"
+)
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/convert_files.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Convert Files — browse the conversions catalog, then convert.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/convert_files.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# The whole catalog: every supported target and its options.
+all = client.conversions.list
+puts "#{all.length} conversions available"
+
+# Narrow it down: which conversions produce a PNG image?
+png = client.conversions.list("image", "png")
+puts "#{png.length} way(s) to produce png"
+
+# Now convert a JPG to PNG.
+result = client.convert(JPG, "png", category: "image")
+path = result.save("convert-files-output.png")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/create_archives.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Create Archives — bundle several remote files into a single ZIP.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/create_archives.rb
+
+require "api2convert"
+
+PDF = "https://example-files.online-convert.com/document/pdf/example.pdf"
+PNG = "https://example-files.online-convert.com/raster%20image/png/example.png"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.jobs.create(
+  {
+    "process" => true,
+    "input" => [
+      { "type" => "remote", "source" => PDF },
+      { "type" => "remote", "source" => PNG }
+    ],
+    "conversion" => [{ "category" => "archive", "target" => "zip" }]
+  }
+)
+
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+outputs = client.jobs.outputs(job.id)
+outputs.each { |output| puts output.uri }

data/examples/create_hashes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Create Hashes — compute the SHA-256 checksum of a remote file.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/create_hashes.rb
+
+require "api2convert"
+
+ZIP = "https://example-files.online-convert.com/archive/zip/example.zip"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(ZIP, "sha256", category: "hash")
+
+# The hash is returned as the output file's contents.
+puts "sha256: #{result.contents}"
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/create_thumbnails.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Create Thumbnails — render a thumbnail of the first PDF page.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/create_thumbnails.rb
+
+require "api2convert"
+
+PDF = "https://example-files.online-convert.com/document/pdf/example.pdf"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  PDF,
+  "thumbnail",
+  { "thumbnail_target" => "png", "width" => 300, "pages" => "first", "dpi" => 150 },
+  category: "operation"
+)
+
+# Save into a directory so the API-provided filename is kept.
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/extract_assets.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Extract Assets — pull the embedded assets out of a document.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/extract_assets.rb
+
+require "api2convert"
+
+DOCX = "https://example-files.online-convert.com/document/docx/example.docx"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(DOCX, "extract-assets", category: "operation")
+puts "job #{result.job.id} is #{result.job.status.code}"
+
+result.outputs.each { |output| puts output.uri }

data/examples/file_analysis.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# File Analysis — extract a file's metadata as JSON.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/file_analysis.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(JPG, "json", category: "metadata")
+puts "job #{result.job.id} is #{result.job.status.code}"
+
+# The analysis result is the output file's JSON body.
+puts result.contents

data/examples/image_operations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Image Operations — resize an image with the resize-image operation.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/image_operations.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(
+  JPG,
+  "resize-image",
+  { "width" => 800, "height" => 600, "resize_by" => "px", "resize_handling" => "keep_aspect_ratio_crop" },
+  category: "operation"
+)
+
+path = result.save("output/")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/job_lifecycle.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Job Lifecycle — drive create -> add input -> start -> wait -> outputs by hand.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/job_lifecycle.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# Stage a job (process: false) so we can attach inputs before starting.
+job = client.jobs.create(
+  { "process" => false, "conversion" => [{ "category" => "image", "target" => "png" }] }
+)
+puts "created job #{job.id}"
+
+# Attach a remote input, then start processing.
+client.jobs.add_input(job.id, { "type" => "remote", "source" => JPG })
+client.jobs.start(job.id)
+
+# Poll to a terminal status (raises on a failed job by default).
+done = client.jobs.wait(job.id)
+puts "job #{done.id} is #{done.status.code}"
+
+# List the produced outputs.
+outputs = client.jobs.outputs(job.id)
+outputs.each { |output| puts output.uri }

data/examples/presets.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Presets — list your saved conversion presets.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/presets.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+presets = client.presets.list(category: "video", target: "mp4")
+puts "#{presets.length} preset(s)"
+
+presets.each { |preset| puts "#{preset.id}: #{preset.name} -> #{preset.target}" }

data/examples/quickstart.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Quickstart — convert a remote file, inspect the job, download the result.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/quickstart.rb
+
+require "api2convert"
+
+JPG = "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+# One-call convert of a remote URL (create -> poll -> ready to download).
+result = client.convert(JPG, "png", category: "image")
+
+# Fetch the finished job by id and print its status.
+job = client.jobs.get(result.job.id)
+puts "job #{job.id} is #{job.status.code}"
+
+# Download the produced output.
+path = result.save("quickstart-output.png")
+puts "saved #{path} (#{File.size(path)} bytes)"

data/examples/rate_limits.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Rate Limits — inspect your account's contracts (quotas and limits).
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/rate_limits.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+contracts = client.contracts.get
+puts contracts.inspect

data/examples/statistics.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Statistics — read your API usage for a given month.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/statistics.rb
+
+require "api2convert"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+stats = client.stats.month("2026-06")
+puts stats.inspect

data/examples/uploading_files.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Uploading Files — convert a local file in one call (convert() uploads it).
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/uploading_files.rb
+
+require "api2convert"
+require "base64"
+require "tmpdir"
+
+# A minimal valid 1x1 PNG so the example needs no binary fixture on disk.
+ONE_PX_PNG = Base64.decode64(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+)
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+Dir.mktmpdir("a2c-upload") do |dir|
+  source = File.join(dir, "pixel.png")
+  File.binwrite(source, ONE_PX_PNG)
+
+  # Hand convert() a local path — it stages the job, uploads the file to the
+  # per-job upload server, starts it and polls to completion.
+  result = client.convert(source, "png", category: "image")
+  path = result.save("uploading-files-output.png")
+  puts "saved #{path} (#{File.size(path)} bytes)"
+end

data/examples/webhooks.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Webhooks — start a conversion and be notified via a callback URL.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/webhooks.rb
+#
+# convert_async returns immediately with a started job; the API POSTs to your
+# callback when it finishes. See examples/webhook.rb for a receiver that verifies
+# the callback signature.
+
+require "api2convert"
+
+DOCX = "https://example-files.online-convert.com/document/docx/example.docx"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.convert_async(
+  DOCX, "pdf",
+  callback: "https://your-app.example.com/api2convert/webhook",
+  category: "document"
+)
+
+puts "started job #{job.id} (#{job.status.code})"
+puts "the API will POST to the callback URL when it completes"

data/lib/api2convert/version.rb

@@ -4,5 +4,5 @@ module Api2Convert
   # The SDK version. Kept in lock-step with the sibling SDKs (PHP, Python, Java,
   # Node.js): all official ports implement the same `docs/SDK_CONTRACT.md` and
   # version together.
-  VERSION = "10.2.0"
+  VERSION = "10.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api2convert
 version: !ruby/object:Gem::Version
-  version: 10.2.0
+  version: 10.2.1
 platform: ruby
 authors:
 - Qaamgo Media GmbH
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies: []
 description: Convert, compress and transform images, documents, audio, video, ebooks,
   archives and CAD — and run operations like OCR, merge, thumbnail and website capture
@@ -23,8 +23,27 @@ files:
 - README.md
 - docs/CHANGELOG.md
 - docs/SDK_CONTRACT.md
-- examples/convert.rb
+- examples/add_watermark.rb
+- examples/audio_operations.rb
+- examples/authentication.rb
+- examples/capture_website.rb
+- examples/compare_files.rb
+- examples/compress_files.rb
+- examples/convert_files.rb
+- examples/create_archives.rb
+- examples/create_hashes.rb
+- examples/create_thumbnails.rb
+- examples/extract_assets.rb
+- examples/file_analysis.rb
+- examples/image_operations.rb
+- examples/job_lifecycle.rb
+- examples/presets.rb
+- examples/quickstart.rb
+- examples/rate_limits.rb
+- examples/statistics.rb
+- examples/uploading_files.rb
 - examples/webhook.rb
+- examples/webhooks.rb
 - lib/api2convert.rb
 - lib/api2convert/client.rb
 - lib/api2convert/config.rb

data/examples/convert.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-# Minimal synchronous conversion example.
-#
-#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/convert.rb path/to/photo.png jpg out.jpg
-#
-# Falls back to converting a public sample image when no source is given.
-
-require "api2convert"
-
-source = ARGV[0] || "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
-target = ARGV[1] || "png"
-destination = ARGV[2] || "output.#{target}"
-
-client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
-
-result = client.convert(source, target)
-path = result.save(destination)
-
-puts "Converted #{source} -> #{path} (#{File.size(path)} bytes)"