selectpdf 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eaf046e0be6119e542567c9aaa8619c54e7f6c99819a84c9d96f2b7b38d21af
-  data.tar.gz: 3cab0ed9984ebd11cfa25dde675327a94ffd37203e9e35e57932910fbd5e956f
+  metadata.gz: 7ae5074b6a4a0b0f2ce43d997aef9038b6167ef433d87398bf22b84e882a0712
+  data.tar.gz: d4db4d73e23f7208ca7bbd2d4cb98aa9a9532c44d93b5a0f788cd5cbf40cf835
 SHA512:
-  metadata.gz: 106e81246f60e07de4cd302133b317624c79784b852974fb77092d3d31ea28d11dc74ec29bda1552c48cb4f7473f0457a42fd187c18893a9d2d9cdc9fa2a83d7
-  data.tar.gz: 026b2222f8282cbf80f0e5b8a8684d0de2ea4a3eb366bb39638175088dcfb75549f9f46d259a08ec205a1df51f6a778c5968c305fab961656c04b9204b7b63ed
+  metadata.gz: 582606dcd6800ed03da64f4205e9057a8371613c364aa278d6115270453fc40b6aa071ebfc4d5758c387949049a6e26bbb1a10655247d65b1f4f3e91e62d580b
+  data.tar.gz: '08773193c4235663f98870d7998b6646f6012e83a477f57deac1ff18facb7a6e75173d7f6c8001a39bbaa563bd3787e54f4769326b0664efdac3f873296c9e93'

data/CHANGELOG.md

@@ -1,5 +1,17 @@
+### 1.6.0
+* Includes the 1.5.0 features of the SelectPdf API clients (there was no separate 1.5.0 Ruby release).
+* Accessible PDF and PDF standards on HtmlToPdfClient: tagged, pdf_standard (new SelectPdf::PdfStandard class: Full, PdfA, PdfA2B, PdfA3A, PdfA3B, PdfA3U, PdfX, PdfSiqQ_A, PdfSiqQ_B) and doc_language.
+* Electronic invoices: new InvoiceClient creates ZUGFeRD / Factur-X hybrid invoices (PDF/A-3 with the invoice XML embedded) from a url or an html string, synchronously or asynchronously. Invoice XML from a file (invoice_xml_file) or from memory (invoice_xml), zugferd_profile, zugferd_relationship, zugferd_schema (new SelectPdf::ZugferdProfile, SelectPdf::ZugferdRelationship, SelectPdf::ZugferdSchema classes). Requires an API key.
+* HtmlToPdfClient: web_page_fixed_size, auth_username, auth_password.
+* 1.5.0: keyless demo mode - HtmlToPdfClient.new with no key, an empty key or 'demo' uses the demo endpoint (watermarked output, 5 pages, Chromium engine). New demo_mode?, demo_response?, clamped_fields, dropped_fields, was_clamped?, was_any_field_dropped?.
+* 1.5.0: typed demo exceptions (subclasses of ApiException): DemoRateLimitException, DemoSafetyException, DemoUnsupportedException. user_password, owner_password and asynchronous calls raise DemoUnsupportedException in demo mode.
+* 1.5.0: response telemetry on every client - credits_total, credits_remaining, mode, execution_mode.
+* 1.5.0: SelectPdf::RenderingEngine::CHROMIUM.
+* Number of pages and job id are read from the X-SelectPdf-Pages and X-SelectPdf-Job-Id response headers. Asynchronous jobs are complete when the job status is no longer 202 Accepted.
+* Fixes: TRUE / FALSE constants (removed in Ruby 3.2) replaced with true / false, including the default arguments of the PdfToTextClient search methods; multipart requests (PDF merge, PDF to text) now send parameters set to false instead of skipping them; cookies are encoded with %20 for spaces, as the API expects.
+
 ### 1.4.0
 * Pdf Merge Client, Pdf To Text Client
 
 ### 1.3.0
-* Html To Pdf Client
+* Html To Pdf Client

data/README.md

@@ -14,6 +14,9 @@ SelectPdf HTML To PDF Online REST API is a professional solution that lets you c
 * Hide web page elements during the conversion.
 * Automatically generate bookmarks during the html to pdf conversion.
 * Support for partial page conversion.
+* Tagged (accessible) PDF and PDF/A, PDF/X, PDF/SiqQ conformance.
+* ZUGFeRD / Factur-X hybrid electronic invoices.
+* Try it without an API key with the keyless demo endpoint.
 * Works in all programming languages.
 
 Sign up for for free to get instant API access to SelectPdf [HTML to PDF API](https://selectpdf.com/html-to-pdf-api/).
@@ -32,14 +35,121 @@ Sign up for for free to get instant API access to SelectPdf [HTML to PDF API](ht
 
         api.page_size = SelectPdf::PageSize::A4
         api.margins = 0
-        api.page_numbers = FALSE
-        api.page_breaks_enhanced_algorithm = TRUE
+        api.page_numbers = false
+        api.page_breaks_enhanced_algorithm = true
 
         api.convert_url_to_file(url, local_file)
     rescue SelectPdf::ApiException => e
         print("An error occurred: #{e}")
     end
 
+### Demo Mode (no API key)
+
+Construct `HtmlToPdfClient` with no key, an empty key or `'demo'` to use the keyless demo endpoint. No signup is required, but the output is watermarked, capped at 5 pages and always rendered with the Chromium engine.
+
+    client = SelectPdf::HtmlToPdfClient.new # or HtmlToPdfClient.new('demo')
+    pdf = client.convert_url('https://selectpdf.com')
+
+    print "Demo mode: #{client.demo_mode?}, demo response: #{client.demo_response?}\n"
+    print "Clamped: #{client.clamped_fields.join(', ')}\n" if client.was_clamped?
+    print "Dropped: #{client.dropped_fields.join(', ')}\n" if client.was_any_field_dropped?
+
+* `demo_mode?` - the client was constructed without a key. `demo_response?` - the last response came from the demo endpoint.
+* `clamped_fields` - parameters the demo endpoint modified (e.g. `max_load_time` is capped to 15 seconds, `engine` is forced to Chromium).
+* `dropped_fields` - parameters the demo endpoint ignored: `auth_username`, `auth_password`, `cookies_string` (set with `cookies`), `raw_parameters`, `pdf_name`, `async`, `pdf_web_elements_selectors`.
+* PDF passwords (`user_password`, `owner_password`) and asynchronous calls are not available in demo mode and raise `SelectPdf::DemoUnsupportedException`.
+* Only public urls are converted. Internal or private hosts are rejected with `SelectPdf::DemoSafetyException`.
+* Per-IP and global rate limits raise `SelectPdf::DemoRateLimitException`.
+
+### Exceptions
+
+All errors raise `SelectPdf::ApiException`. The demo endpoint errors raise typed subclasses, so you can react to them without parsing the message:
+
+| Exception | Raised when | Attributes |
+| --- | --- | --- |
+| `SelectPdf::DemoRateLimitException` | the demo rate limit is reached (HTTP 429 or 503) | `status_code`, `reason` (`per_ip`, `concurrency`, `daily_cap`), `retry_after`, `upgrade_url`, `response_body` |
+| `SelectPdf::DemoSafetyException` | a url field references a non-public host (HTTP 400) | `status_code`, `field`, `reason`, `response_body` |
+| `SelectPdf::DemoUnsupportedException` | a feature is not available in demo mode (HTTP 400, or before the request is sent with `status_code` 0) | `status_code`, `field`, `upgrade_url`, `response_body` |
+
+    begin
+        client = SelectPdf::HtmlToPdfClient.new
+        client.convert_url_to_file('https://selectpdf.com', 'Test.pdf')
+    rescue SelectPdf::DemoRateLimitException => e
+        print("Demo rate limit (#{e.reason}). Retry after #{e.retry_after}s. Upgrade: #{e.upgrade_url}\n")
+    rescue SelectPdf::DemoUnsupportedException => e
+        print("Feature '#{e.field}' not available in demo mode.\n")
+    rescue SelectPdf::ApiException => e
+        print("An error occurred: #{e}")
+    end
+
+### Response Telemetry
+
+Every client exposes what the server reported for the most recent call:
+
+* `number_of_pages` - number of pages of the resulted PDF.
+* `credits_total` - monthly conversion limit of the subscription (-1 = unlimited, nil when not reported, e.g. in demo mode).
+* `credits_remaining` - conversions remaining this month (-1 = unlimited, nil when not reported).
+* `mode` - `production` or `demo`.
+* `execution_mode` - server-side execution path of the conversion (e.g. `worker`).
+
+### Accessible PDF and PDF Standards
+
+    client = SelectPdf::HtmlToPdfClient.new(api_key)
+
+    client.tagged = true # tagged (accessible) PDF - needs the Blink or Chromium engine
+    client.doc_title = 'Accessible document' # a tagged document needs a title
+    client.doc_language = 'en-US' # document language (PDF /Lang entry)
+    client.pdf_standard = SelectPdf::PdfStandard::PDF_A3A # Full, PdfA, PdfA2B, PdfA3A, PdfA3B, PdfA3U, PdfX, PdfSiqQ_A, PdfSiqQ_B
+    client.rendering_engine = SelectPdf::RenderingEngine::CHROMIUM # optional - the API promotes tagged requests to Chromium
+
+    client.convert_url_to_file('https://selectpdf.com', 'Accessible.pdf')
+
+Other parameters added in 1.6.0:
+
+* `web_page_fixed_size` - leave out the content below `web_page_height` instead of letting the page flow onto further pages.
+* `auth_username`, `auth_password` - HTTP Basic authentication credentials for the web page being converted.
+
+See [HTML to PDF API parameters](https://selectpdf.com/html-to-pdf-api-parameters/) for the full list of parameters.
+
+## Electronic Invoice API
+
+`SelectPdf::InvoiceClient` creates ZUGFeRD / Factur-X hybrid electronic invoices: one PDF/A-3 document carrying both the page a human reads and the invoice XML an accounting system reads. It derives from `HtmlToPdfClient`, so every conversion setting applies too. An API key is required - the demo endpoint does not create invoices.
+
+### Features
+
+* Create the visible invoice from a url or an html string, synchronously or asynchronously.
+* Embed the invoice XML from a local file (`invoice_xml_file`) or from memory (`invoice_xml`).
+* Profiles: `MINIMUM`, `BASIC_WL`, `BASIC`, `EN16931`, `EXTENDED`, `XRECHNUNG` (`SelectPdf::ZugferdProfile`).
+* Optional relationship (`SelectPdf::ZugferdRelationship`) - derived from the profile when not set - and schema (`SelectPdf::ZugferdSchema`, Factur-X 1.0 by default).
+* The carrier is PDF/A-3A by default; `PDF_A3B` and `PDF_A3U` are also accepted.
+
+### Sample Code
+
+    require 'selectpdf'
+
+    api_key = 'Your API key here'
+
+    begin
+        client = SelectPdf::InvoiceClient.new(api_key)
+
+        client.invoice_xml_file = 'factur-x.xml' # or client.invoice_xml = xml_string
+        client.zugferd_profile = SelectPdf::ZugferdProfile::EN16931
+        # client.zugferd_relationship = SelectPdf::ZugferdRelationship::DATA # optional
+        # client.zugferd_schema = SelectPdf::ZugferdSchema::FACTUR_X_10 # optional
+
+        client.create_from_html_string_to_file('<h1>Invoice INV-2026-001</h1>', 'Invoice.pdf')
+        # client.create_from_url_to_file('https://your-app.example/invoices/INV-2026-001', 'Invoice.pdf')
+        # pdf = client.create_from_html_string_async('<h1>Invoice INV-2026-001</h1>')
+
+        print "Finished! Number of pages: #{client.number_of_pages}.\n"
+    rescue SelectPdf::ApiException => e
+        print("An error occurred: #{e}")
+    end
+
+Available methods: `create_from_url`, `create_from_url_to_stream`, `create_from_url_to_file`, `create_from_html_string`, `create_from_html_string_with_base_url`, `create_from_html_string_to_stream`, `create_from_html_string_to_stream_with_base_url`, `create_from_html_string_to_file`, `create_from_html_string_with_base_url_to_file` and the asynchronous `create_from_url_async`, `create_from_url_to_stream_async`, `create_from_url_to_file_async`, `create_from_html_string_async`, `create_from_html_string_with_base_url_async`, `create_from_html_string_to_stream_async`, `create_from_html_string_to_file_async`.
+
+See `samples/electronic_invoice.rb` for a complete sample with an inline invoice XML.
+
 ## Pdf Merge API
 
 SelectPdf Pdf Merge REST API is an online solution that lets you merge local or remote PDFs into a final PDF document.