labelzoom 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cb5cacebc8dce60a6d1202a23295d51237e834593f029aa10b4ce32d1c9f32e9
+  data.tar.gz: 329926fc32ac63622ef6e24fe530241c7771dc231b0bf24b45c16a20e2c73ff4
+SHA512:
+  metadata.gz: d8faac862c608c291a469f0f7657911abd74df7504d3882cac124bb2de9bb914cece3a3ac121ae5effcd5f3d4ad80b50050d504a8b4ccd4d399f253af247ced9
+  data.tar.gz: 6fe2f0af475e5844c217e6df13cc1f799af72e0ccaf17034590f81040fa5e10622f8b8bc23d4c99f6c102a0112da1d7d8bc8fe1ebc24b8283317c4b214564cd3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LabelZoom
+
+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,176 @@
+![LabelZoom Logo](../docs/LabelZoom_Logo_f_400px.png)
+
+# LabelZoom Ruby SDK
+
+Official Ruby client for the [LabelZoom API](https://api.labelzoom.com). Converts barcode labels
+between ZPL, EPL, TSPL, DPL, PDF, LabelZoom XML/JSON, and raster images.
+
+Ruby 3.1+. **No runtime dependencies** — `net/http`, `json`, `uri` and `openssl` are all standard
+library.
+
+## Install
+
+```sh
+gem install labelzoom
+```
+
+```ruby
+gem "labelzoom", "~> 1.0"
+```
+
+<details>
+<summary>Build from source</summary>
+
+```sh
+git clone https://github.com/labelzoom/labelzoom-sdk.git
+cd labelzoom-sdk/ruby
+bundle install && bundle exec rake
+```
+</details>
+
+## Quick start
+
+**An API key is optional.** Without one you get the free tier — watermarked output, first label
+only, a 1 MB request cap, and no multi-page, JSON-target, or image-to-image conversion.
+
+```ruby
+require "labelzoom"
+
+client = LabelZoom::Client.new          # anonymous; this works
+
+result = client.convert(:zpl, :png, "^XA^FO20,20^A0N,28^FDHello^FS^XZ",
+                        dpi: 300,
+                        label: { width: 4, height: 6 })
+
+result.save("label.png")
+```
+
+With a credential:
+
+```ruby
+client = LabelZoom::Client.new(api_key: "lz_live_...")
+```
+
+Passing nothing reads `LABELZOOM_API_KEY` from the environment. Passing `api_key: nil` — or an
+empty string — forces the free tier and suppresses that fallback.
+
+## Formats
+
+**Sources (13):** `:zpl` `:epl` `:tspl` `:dpl` `:xml` `:json` `:pdf` `:png` `:bmp` `:gif` `:jpeg`
+`:jpg` `:url`
+
+**Targets (11):** `:zpl` `:epl` `:tspl` `:dpl` `:xml` `:json` `:pdf` `:png` `:bmp` `:gif` `:jpeg`
+
+`:jpg` is an input spelling that normalizes to `jpeg` on the wire, and `:url` tells the server to
+go fetch a document rather than naming a format — so neither is a target. The statically typed
+SDKs make that a compile error; Ruby raises `LabelZoom::ValidationError` (an `ArgumentError`) on
+the call, before any request goes out.
+
+The printer languages round-trip: `pdf`→`epl` and `zpl`→`tspl` are real conversions. Their output
+is `text/plain`, but EPL's `GW` and TSPL's `BITMAP` commands inline raw binary, so read
+`result.bytes` rather than `result.text` whenever a label might carry graphics.
+
+## Options
+
+Options are keyword arguments with **nested hashes**, and **only what you pass is sent** — the SDK
+never fills in a client-side default, so a change to a server default reaches you without a gem
+upgrade.
+
+```ruby
+client.convert(:zpl, :png, zpl,
+               dpi: 300,                                  # server default 203
+               rotation: 90,                              # must be a multiple of 90
+               scaling: 75.0,                             # percent; server default 100
+               color_mode: "GRAYSCALE",
+               darkness: 60,                              # 0-100 luminance threshold
+               position: { x: 5, y: 15 },
+               watermark: false,                          # an explicit false IS sent
+               label: { width: 4.0, height: 6.0 },
+               pdf: { conversion_mode: "IMAGE", page_number: 0 },
+               zpl: { commands_to_ignore: ["^PQ"], image_compression: "Z64" },
+               data: [{ sku: "1234" }])
+```
+
+Two units are routinely misread and are pinned by the shared fixtures:
+
+- `label:` is in **inches**, not dots. Omit it entirely to have the server detect the size.
+- `pdf: { page_number: }` is **0-based**. Omit it to convert every page.
+
+`data:` is one record per output label; a single Hash is wrapped rather than rejected. `extra:`
+carries anything the SDK does not model yet — unknown keys are ignored server-side, so it is a
+safe forward-compatibility hatch.
+
+A misspelled key raises rather than vanishing. Ruby has no compiler to catch
+`label: { widht: 4 }`, and the server ignores keys it does not recognize, so a silent drop would
+hand you a wrong label and no signal.
+
+## Errors
+
+Every non-2xx response becomes a typed error carrying the status, the message, the raw body, and
+the `X-LZ-Request-Id` support handle:
+
+```ruby
+begin
+  client.convert(:zpl, :json, zpl)
+rescue LabelZoom::ForbiddenError => e
+  warn "paywall" if e.paid_feature?
+rescue LabelZoom::APIError => e
+  warn "request #{e.request_id} failed with #{e.status}: #{e.message}"
+end
+```
+
+`BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `PayloadTooLargeError`,
+`RateLimitedError` and `ServerError` all descend from `LabelZoom::APIError`, so one `rescue`
+catches the lot.
+
+`LabelZoom::ValidationError` deliberately does **not**: it reports a request rejected locally,
+before any network call, which is a bug in the calling code rather than a server response. It
+descends from `ArgumentError`, so rescuing `APIError` to implement a fallback will not swallow it.
+
+## Retries
+
+429s, 5xx responses and transport failures are retried automatically — twice by default, for three
+attempts — with a 1s/2s/4s backoff under full jitter. A `Retry-After` header is honoured on any
+retryable status when it asks for longer than the backoff would wait. No other 4xx is ever retried.
+
+```ruby
+client = LabelZoom::Client.new(max_retries: 0)   # disable retrying
+```
+
+## Testing your own code
+
+The sleeper and the environment lookup are both injectable, so a test never sleeps and never picks
+up a developer's real key:
+
+```ruby
+slept = []
+client = LabelZoom::Client.new(
+  sleeper: ->(seconds) { slept << seconds },
+  jitter: false,
+  env: {}
+)
+```
+
+Stub HTTP with [WebMock](https://github.com/bblimke/webmock), which is what this gem's own suite
+uses — it intercepts at the `Net::HTTP` layer, so the real request-construction path is exercised
+rather than bypassed.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # rubocop + rspec
+```
+
+The spec suite is the shared conformance fixtures in [`../conformance/`](../conformance/) — the
+same cases the .NET, Node, Java, Python, PHP and Go suites run — plus an assertion that it
+executed every one of them.
+
+Ruby declares the two `typecheck/*` cases skipped in
+[`../conformance/skips/ruby.json`](../conformance/skips/ruby.json), because Ruby has no compile
+step. `spec/labelzoom/formats_spec.rb` is what makes that skip's stated reason true rather than
+merely convenient: it asserts the runtime guard the skip claims exists.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/labelzoom/client.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module LabelZoom
+  # Converts labels through the LabelZoom API.
+  #
+  # Authentication is optional. Without a credential the API serves a free tier:
+  # watermarked output, the first label only, a 1 MB request cap, and no multi-page,
+  # JSON-target or image-to-image conversion. Constructing a client with no key is
+  # therefore a supported, tested path rather than an error.
+  class Client
+    # The production API host.
+    DEFAULT_BASE_URL = "https://api.labelzoom.com"
+
+    # The environment variable consulted when no credential is configured.
+    API_KEY_ENVIRONMENT_VARIABLE = "LABELZOOM_API_KEY"
+
+    # The support handle the gateway stamps on every response. Net::HTTP looks headers up
+    # case-insensitively, which matters here: the gateway sets X-LZ-Request-Id but CORS
+    # exposes it as X-LZ-Request-ID.
+    REQUEST_ID_HEADER = "x-lz-request-id"
+
+    # E2 caps the derived message here. APIError#raw_body keeps the whole body.
+    MAX_MESSAGE_LENGTH = 512
+
+    # Statuses worth retrying. Rule F1: nothing else, ever.
+    RETRYABLE_STATUSES = ->(status) { status == 429 || status >= 500 }
+
+    # E2's last resort, when a body is empty and the reason phrase is too. Net::HTTP does
+    # not always surface a phrase, so this is derived from a table rather than the wire.
+    REASON_PHRASES = {
+      400 => "Bad Request", 401 => "Unauthorized", 403 => "Forbidden", 404 => "Not Found",
+      406 => "Not Acceptable", 413 => "Payload Too Large", 429 => "Too Many Requests",
+      500 => "Internal Server Error", 502 => "Bad Gateway", 503 => "Service Unavailable",
+      504 => "Gateway Timeout"
+    }.freeze
+
+    # @param api_key [String, nil, LabelZoom::UNSET] an lz_live_/lz_test_ key or a JWT.
+    #   Left at +UNSET+ the client reads +LABELZOOM_API_KEY+ from +env+. Passing +nil+ or
+    #   an empty String forces anonymous mode and suppresses that fallback.
+    # @param base_url [String] a path prefix is preserved, so a reverse proxy at
+    #   https://proxy.example.com/labelzoom works.
+    # @param max_retries [Integer] retries after the initial attempt. 0 disables retrying.
+    # @param timeout [Numeric] per-attempt read and open timeout, in seconds.
+    # @param user_agent_suffix [String, nil] appended to the SDK's own User-Agent.
+    # @param sleeper [#call, nil] replaces the delay between retries. Substitute a
+    #   recording no-op in tests so the retry paths cost no wall-clock time.
+    # @param jitter [Boolean] full jitter on the retry backoff. Turn it off for
+    #   deterministic tests; leave it on in production, where it is what stops a fleet
+    #   retrying in lockstep.
+    # @param env [#[]] the environment lookup. Injecting it keeps a developer's real key
+    #   out of a test's outcome.
+    # @param http_builder [#call, nil] builds the Net::HTTP instance. An escape hatch for
+    #   proxies and custom TLS; the conformance suite uses WebMock instead.
+    def initialize(api_key: UNSET, base_url: DEFAULT_BASE_URL, max_retries: 2, timeout: 60,
+                   user_agent_suffix: nil, sleeper: nil, jitter: true, env: ENV,
+                   http_builder: nil)
+      raise ArgumentError, "max_retries cannot be negative" if max_retries.negative?
+
+      # All trailing slashes, not one: a base URL of "https://api.labelzoom.com///" must
+      # still produce a single-slash path.
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @credential = resolve_credential(api_key, env)
+      @max_retries = max_retries
+      @timeout = timeout
+      @sleeper = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+      @jitter = jitter
+      @http_builder = http_builder
+
+      # The server parses a "LabelZoomStudio/" User-Agent prefix as a Studio version and
+      # silently changes PDF handling for versions <= 1.8.2, so the SDK's own token must
+      # come first.
+      suffix = user_agent_suffix.to_s.strip
+      @user_agent = "labelzoom-ruby-sdk/#{VERSION} (ruby/#{RUBY_VERSION})"
+      @user_agent += " #{suffix}" unless suffix.empty?
+    end
+
+    # Whether a credential was resolved. False means requests go out on the anonymous free
+    # tier, which is a supported mode rather than an error.
+    def authenticated? = !@credential.nil?
+
+    # Runs one conversion.
+    #
+    # @param source [Symbol] the format of +body+.
+    # @param target [Symbol] the format to produce.
+    # @param body [String] the document. For +:url+ it is the URL to fetch, as text.
+    # @param base64_text [Boolean] send +body+ as base64 +text/plain+ rather than the
+    #   source's own media type. Only the binary sources support it.
+    # @param options [Hash] conversion parameters, as nested keyword arguments --
+    #   +label: { width: 4, height: 6 }+ rather than Python's flattened +label_width+.
+    #   Only what you pass is sent; the SDK never fills in a client-side default, so a
+    #   change to a server default reaches you without a gem upgrade.
+    #
+    #   +label+ is in INCHES, not dots, and omitting it entirely asks the server to detect
+    #   the size. +pdf: { page_number: }+ is 0-BASED; omit it to convert every page.
+    #
+    # @return [ConversionResult]
+    # @raise [ValidationError] if the request is rejected locally, before any network call.
+    # @raise [APIError] on any non-2xx response.
+    def convert(source, target, body, base64_text: false, **options)
+      source = Formats.source!(source)
+      target = Formats.target!(target)
+      body = body.to_s
+
+      if body.empty?
+        # The gateway rejects a zero-length body with 400; catching it here saves a round
+        # trip and gives a clearer message.
+        raise ValidationError.new("body",
+                                  "Source body cannot be empty; the API rejects zero-length " \
+                                  "requests.")
+      end
+
+      params = Options.serialize(**options)
+      uri = build_uri(source, target, params)
+      headers = build_headers(source, base64_text)
+
+      execute(uri, headers, body)
+    end
+
+    # The URL a given conversion would be posted to. Exposed because it is the first thing
+    # anyone debugging a proxy or a base-URL override wants to see.
+    def build_uri(source, target, params = nil)
+      # Concatenated, not resolved: a base URL carrying a path prefix
+      # (https://proxy.example.com/labelzoom) must keep it, which URI.join would discard.
+      url = "#{@base_url}/api/v2/convert/#{Formats.source_token(source)}/to/" \
+            "#{Formats.target_token(target)}"
+      # Rule C7: no options means a bare URL, not an empty query string.
+      url += "?#{URI.encode_www_form("params" => params)}" unless params.nil?
+      URI.parse(url)
+    end
+
+    private
+
+    def resolve_credential(api_key, env)
+      if UNSET.equal?(api_key)
+        value = env[API_KEY_ENVIRONMENT_VARIABLE]
+        return value.nil? || value.empty? ? nil : value
+      end
+
+      # An explicit nil or "" forces anonymous and must not fall back to the environment.
+      api_key.nil? || api_key.empty? ? nil : api_key
+    end
+
+    def build_headers(source, base64_text)
+      headers = {
+        "Content-Type" => base64_text ? "text/plain" : Formats.media_type(source),
+        # Accept must be */*. The server's `produces` list omits image/gif, image/bmp and
+        # image/jpeg, so naming the target's exact media type yields a 406 from content
+        # negotiation before the handler ever runs.
+        "Accept" => "*/*",
+        "User-Agent" => @user_agent
+      }
+      headers["Authorization"] = "Bearer #{@credential}" unless @credential.nil?
+      headers
+    end
+
+    def execute(uri, headers, body)
+      attempts = @max_retries + 1
+
+      (1..).each do |attempt|
+        begin
+          response = perform(uri, headers, body)
+        rescue *transport_exceptions => e
+          if attempt >= attempts
+            raise TransportError, "labelzoom: request to #{uri} failed: #{e.message}"
+          end
+
+          delay(attempt, nil)
+          next
+        end
+
+        status = response.code.to_i
+        return build_result(response, status) if status.between?(200, 299)
+
+        retry_after = retry_after_seconds(response)
+        if attempt >= attempts || !RETRYABLE_STATUSES.call(status)
+          raise error_for(response, status, retry_after)
+        end
+
+        delay(attempt, retry_after)
+      end
+    end
+
+    def perform(uri, headers, body)
+      http = @http_builder&.call(uri) || Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = Net::HTTP::Post.new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body
+
+      http.start { |session| session.request(request) }
+    end
+
+    def transport_exceptions
+      [SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, IOError,
+       OpenSSL::SSL::SSLError]
+    end
+
+    def build_result(response, status)
+      ConversionResult.new(
+        bytes: (response.body || "").dup.force_encoding(Encoding::BINARY),
+        status: status,
+        content_type: response["content-type"],
+        request_id: response[REQUEST_ID_HEADER]
+      )
+    end
+
+    def error_for(response, status, retry_after)
+      raw_body = (response.body || "").dup.force_encoding(Encoding::BINARY)
+      message = extract_message(raw_body, REASON_PHRASES[status])
+      common = { status: status, request_id: response[REQUEST_ID_HEADER], raw_body: raw_body }
+
+      case status
+      when 400 then BadRequestError.new(message, **common)
+      when 401 then UnauthorizedError.new(message, **common)
+      when 403
+        ForbiddenError.new(message, paid_feature: message.match?(/paid feature/i), **common)
+      when 404 then NotFoundError.new(message, **common)
+      when 413 then PayloadTooLargeError.new(message, **common)
+      when 429 then RateLimitedError.new(message, retry_after_seconds: retry_after, **common)
+      when 500.. then ServerError.new(message, **common)
+      else
+        # Anything else non-2xx still becomes a typed error rather than being swallowed --
+        # a 406 from content negotiation is the one that actually shows up in practice.
+        APIError.new(message, **common)
+      end
+    end
+
+    # Both shapes in play put the detail on "message": the gateway returns
+    # {"message": "..."} and Spring returns {timestamp, status, error, message, path}.
+    # Anything else -- a rate-limit body keyed on "error", an HTML 502, a truncated JSON
+    # fragment -- falls through to the raw text, then to the reason phrase.
+    def extract_message(raw_body, reason_phrase)
+      text = raw_body.dup.force_encoding(Encoding::UTF_8).scrub
+      unless text.strip.empty?
+        begin
+          parsed = JSON.parse(text)
+          detail = parsed["message"] if parsed.is_a?(Hash)
+          return truncate(detail) if detail.is_a?(String) && !detail.strip.empty?
+        rescue JSON::ParserError
+          # Not JSON, or malformed. The raw body is still the most useful thing available,
+          # and a parse failure must not mask the HTTP error.
+        end
+        return truncate(text.strip)
+      end
+
+      return reason_phrase if reason_phrase && !reason_phrase.strip.empty?
+
+      "The LabelZoom API returned an error with no response body."
+    end
+
+    def truncate(value)
+      value.length <= MAX_MESSAGE_LENGTH ? value : value[0, MAX_MESSAGE_LENGTH]
+    end
+
+    # Read from the RESPONSE, on any retryable status. Deliberately not read off the typed
+    # 429 error: RFC 9110 allows Retry-After on a 503 too, and a 503 asking for 5 seconds
+    # must not be retried after a 1-second backoff.
+    def retry_after_seconds(response)
+      header = response["retry-after"]
+      return nil if header.nil? || header.strip.empty?
+
+      begin
+        return Float(header.strip)
+      rescue ArgumentError
+        # Not a number; try the HTTP-date form below.
+      end
+
+      begin
+        [0.0, Time.httpdate(header) - Time.now].max.ceil.to_f
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # 1s, 2s, 4s with full jitter, overridden by a longer Retry-After.
+    def delay(attempt, retry_after)
+      backoff = 2.0**(attempt - 1)
+      wait = @jitter ? backoff * Kernel.rand : backoff
+
+      # The server knows better than the backoff curve when it tells us how long to wait.
+      wait = retry_after if retry_after && retry_after > wait
+
+      @sleeper.call(wait)
+    end
+  end
+end

data/lib/labelzoom/conversion_result.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module LabelZoom
+  # The outcome of a successful conversion.
+  #
+  # {#bytes} is authoritative. PDF, PNG, BMP, GIF and JPEG targets are binary, so treating
+  # the response as text would silently corrupt five of the eleven targets -- and EPL and
+  # TSPL reach the same hazard through a +text/plain+ response, because their +GW+ and
+  # +BITMAP+ commands inline a raw 1-bpp payload.
+  class ConversionResult
+    # @return [String] the response body as binary (ASCII-8BIT), exactly as the server
+    #   sent it. Note this is a String of bytes, not String#bytes' Array of Integers.
+    attr_reader :bytes
+
+    # @return [String, nil] the response Content-Type header.
+    attr_reader :content_type
+
+    # @return [Integer] the HTTP status code, always 2xx here.
+    attr_reader :status
+
+    # @return [String, nil] the X-LZ-Request-Id response header. The support handle.
+    attr_reader :request_id
+
+    def initialize(bytes:, status:, content_type: nil, request_id: nil)
+      @bytes = bytes
+      @status = status
+      @content_type = content_type
+      @request_id = request_id
+    end
+
+    # {#bytes} decoded with the response charset, defaulting to UTF-8.
+    #
+    # Safe for the textual targets. For a binary target, or an EPL/TSPL label that might
+    # carry graphics, read {#bytes} instead.
+    #
+    # Memoized rather than computed in the constructor: a 5 MB PNG's bytes should never be
+    # run through a decoder just because someone built a result object.
+    #
+    # @return [String]
+    def text
+      @text ||= decode
+    end
+
+    # Writes {#bytes} to +path+, in binary mode.
+    def save(path)
+      File.binwrite(path, bytes)
+      path
+    end
+
+    def to_s = text
+
+    private
+
+    # Not a hardcoded UTF-8 decode: the API serves ISO-8859-1 for some conversions, and a
+    # byte like 0xE9 is not valid UTF-8 -- it would come back as U+FFFD rather than "é".
+    def decode
+      charset = content_type.to_s[/charset\s*=\s*"?([^;"]+)"?/i, 1]&.strip
+      source = charset.nil? || charset.empty? ? Encoding::UTF_8 : Encoding.find(charset)
+      bytes.dup.force_encoding(source).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue ArgumentError, Encoding::ConverterNotFoundError
+      # An unrecognized charset is not worth failing an otherwise good conversion.
+      bytes.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+  end
+end

data/lib/labelzoom/errors.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module LabelZoom
+  # Base class for everything this gem raises on its own behalf.
+  class Error < StandardError; end
+
+  # Base class for every error the LabelZoom API returns.
+  #
+  # Rescue this to handle them all. Note that {ValidationError} deliberately does *not*
+  # descend from it.
+  class APIError < Error
+    # @return [Integer] the HTTP status code the API returned.
+    attr_reader :status
+
+    # @return [String, nil] the X-LZ-Request-Id response header, if present. Quote this to
+    #   LabelZoom support -- it identifies the exact request server-side.
+    attr_reader :request_id
+
+    # @return [String] the raw response body, untruncated. {#message} is derived from it
+    #   and capped at 512 characters; this is not.
+    attr_reader :raw_body
+
+    def initialize(message, status:, request_id: nil, raw_body: "")
+      super(message)
+      @status = status
+      @request_id = request_id
+      @raw_body = raw_body
+    end
+  end
+
+  # HTTP 400. The request was malformed or the conversion path is invalid.
+  class BadRequestError < APIError; end
+
+  # HTTP 401. The supplied credential was rejected.
+  class UnauthorizedError < APIError; end
+
+  # HTTP 403. The credential is valid but not entitled to this operation.
+  class ForbiddenError < APIError
+    def initialize(message, paid_feature: false, **kwargs)
+      super(message, **kwargs)
+      @paid_feature = paid_feature
+    end
+
+    # True when this 403 is a paywall rather than a permissions problem -- "JSON export is
+    # a paid feature" and friends. By far the most common anonymous-tier failure, so it
+    # gets a predicate instead of leaving callers to match strings.
+    def paid_feature? = @paid_feature
+  end
+
+  # HTTP 404. The conversion path does not exist.
+  class NotFoundError < APIError; end
+
+  # HTTP 413. The body exceeded the tier's limit -- 1 MB on the anonymous free tier.
+  class PayloadTooLargeError < APIError; end
+
+  # HTTP 429. Too many requests.
+  class RateLimitedError < APIError
+    # @return [Float, nil] Retry-After in seconds, when the server sent one. The client
+    #   already honours this during its own retries; this exposes it for callers doing
+    #   their own.
+    attr_reader :retry_after_seconds
+
+    def initialize(message, retry_after_seconds: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after_seconds = retry_after_seconds
+    end
+  end
+
+  # HTTP 5xx. Retried automatically before surfacing.
+  class ServerError < APIError; end
+
+  # A transport-level failure: the request never got a response.
+  class TransportError < Error; end
+
+  # A request rejected locally, before any network call.
+  #
+  # Deliberately an ArgumentError and *not* an {APIError}: this is a bug in the calling
+  # code, not a server response. It carries no status, it is never retried, and a caller
+  # rescuing {APIError} to implement fallback behaviour should not swallow it.
+  #
+  # This is also what makes conformance/skips/ruby.json's stated reason literally true:
+  # Ruby has no compile step, so a source-only format passed as a target is caught here.
+  class ValidationError < ArgumentError
+    # @return [String] the conversion parameter at fault, named as it appears on the wire.
+    attr_reader :parameter
+
+    def initialize(parameter, message)
+      super(message)
+      @parameter = parameter
+    end
+  end
+end

data/lib/labelzoom/formats.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module LabelZoom
+  # The format metadata table, defined once.
+  #
+  # Deliberately the only place a format's media type appears. The superseded .NET design
+  # had a builder class per format, each independently knowing this mapping, and they
+  # drifted -- one of them emitted the source type as the target.
+  module Formats
+    # Every accepted source, in the contract's order. +:jpg+ is an input spelling that
+    # normalizes to +:jpeg+ on the wire; +:url+ tells the server to go fetch a document
+    # rather than naming a format.
+    SOURCE_FORMATS = %i[zpl epl tspl dpl xml json pdf png bmp gif jpeg jpg url].freeze
+
+    # Every accepted target. There is no +:url+ -- it is a fetch instruction, not an output
+    # format -- and no +:jpg+, which is a source-side spelling only.
+    #
+    # The printer languages round-trip: +:epl+, +:tspl+ and +:dpl+ became targets in
+    # contract 1.1.0, when the printer-language writers shipped.
+    TARGET_FORMATS = %i[zpl epl tspl dpl xml json pdf png bmp gif jpeg].freeze
+
+    MEDIA_TYPES = {
+      zpl: "text/plain",
+      epl: "text/plain",
+      tspl: "text/plain",
+      dpl: "text/plain",
+      xml: "application/xml",
+      json: "application/json",
+      pdf: "application/pdf",
+      png: "image/png",
+      bmp: "image/bmp",
+      gif: "image/gif",
+      jpeg: "image/jpeg",
+      jpg: "image/jpeg",
+      # The body is the URL itself.
+      url: "text/plain"
+    }.freeze
+
+    # Colour reduction. Server default GRAYSCALE.
+    COLOR_MODES = %w[BW GRAYSCALE COLOR].freeze
+
+    # How a PDF source is interpreted. Server default IMAGE.
+    PDF_CONVERSION_MODES = %w[IMAGE NATIVE].freeze
+
+    # Encoding of images embedded in ZPL output. Server default Z64.
+    ZPL_IMAGE_COMPRESSIONS = %w[Z64 COMPRESSED_HEX].freeze
+
+    module_function
+
+    # @return [Symbol] the validated source format.
+    # @raise [ValidationError] if it is not a source the API accepts.
+    def source!(format)
+      symbol = format.to_s.downcase.to_sym
+      return symbol if SOURCE_FORMATS.include?(symbol)
+
+      raise ValidationError.new("source",
+                                "#{format.inspect} is not a source format the LabelZoom API " \
+                                "accepts. Expected one of: #{SOURCE_FORMATS.join(", ")}.")
+    end
+
+    # @return [Symbol] the validated target format.
+    # @raise [ValidationError] if it is not a target the API produces. This is where Ruby
+    #   enforces what the statically typed SDKs enforce at compile time -- passing +:url+
+    #   or +:jpg+ as a target is caught here.
+    def target!(format)
+      symbol = format.to_s.downcase.to_sym
+      return symbol if TARGET_FORMATS.include?(symbol)
+
+      raise ValidationError.new("target",
+                                "#{format.inspect} is not a target format the LabelZoom API " \
+                                "produces. Expected one of: #{TARGET_FORMATS.join(", ")}.")
+    end
+
+    # The path segment for a source. +:jpg+ normalizes to "jpeg" (rule A2).
+    def source_token(format) = format == :jpg ? "jpeg" : format.to_s
+
+    # The path segment for a target. Targets need no normalization.
+    def target_token(format) = format.to_s
+
+    # The request Content-Type for a source.
+    def media_type(format) = MEDIA_TYPES.fetch(format)
+  end
+
+  SOURCE_FORMATS = Formats::SOURCE_FORMATS
+  TARGET_FORMATS = Formats::TARGET_FORMATS
+end

data/lib/labelzoom/options.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+
+# See lib/labelzoom.rb for the module overview.
+module LabelZoom
+  # The sentinel for "the caller did not pass this".
+  #
+  # Not +nil+, and not a missing key in a +**options+ splat. +watermark: false+ and
+  # +pdf: { page_number: 0 }+ are meaningful values a caller sets deliberately, so
+  # falsiness cannot stand in for absence -- the same reason the Python SDK carries an
+  # +UNSET+ singleton.
+  UNSET = Object.new
+  def UNSET.inspect = "LabelZoom::UNSET"
+  UNSET.freeze
+
+  # Renders conversion options as the +params+ JSON value.
+  #
+  # Everything travels in one <tt>?params=&lt;JSON&gt;</tt> parameter, never dot-notation.
+  # The API accepts both and merges them, but dot-notation cannot express every parameter
+  # -- <tt>?data=[{}]</tt> is rejected with 400 while <tt>?params={"data":[{}]}</tt>
+  # succeeds. One serialization path, no special cases.
+  module Options
+    # Nested option hashes, and the wire key each of their keys maps to. Anything not
+    # listed raises rather than being dropped: Ruby has no compiler to catch
+    # `label: { widht: 4 }`, and the server ignores unknown keys, so a silent drop would
+    # hand the caller a wrong label and no signal.
+    NESTED_KEYS = {
+      position: { x: "x", y: "y" },
+      label: { width: "width", height: "height" },
+      pdf: { conversion_mode: "conversionMode", page_number: "pageNumber" },
+      zpl: { commands_to_ignore: "commandsToIgnore", image_compression: "imageCompression" }
+    }.freeze
+
+    SCALAR_KEYS = {
+      dpi: "dpi",
+      rotation: "rotation",
+      scaling: "scaling",
+      color_mode: "colorMode",
+      darkness: "darkness",
+      watermark: "watermark",
+      dialect: "dialect"
+    }.freeze
+
+    module_function
+
+    # @return [String, nil] the params JSON, or nil when nothing was set -- in which case
+    #   no query parameter is emitted at all (rule C7).
+    def serialize(**options)
+      params = {}
+
+      SCALAR_KEYS.each do |key, wire_key|
+        value = options.fetch(key, UNSET)
+        next if UNSET.equal?(value)
+
+        params[wire_key] = validate_scalar(key, value)
+      end
+
+      NESTED_KEYS.each do |key, mapping|
+        value = options.fetch(key, UNSET)
+        next if UNSET.equal?(value)
+
+        params[key.to_s] = nested(key, value, mapping)
+      end
+
+      data = options.fetch(:data, UNSET)
+      params["data"] = normalize_data(data) unless UNSET.equal?(data)
+
+      extra = options.fetch(:extra, UNSET)
+      params.merge!(stringify(extra)) unless UNSET.equal?(extra)
+
+      params.empty? ? nil : JSON.generate(params)
+    end
+
+    def validate_scalar(key, value)
+      case key
+      when :rotation
+        # Rejected locally: the server would 400, and this is unambiguously a caller bug.
+        unless value.is_a?(Numeric) && (value % 90).zero?
+          raise ValidationError.new("rotation",
+                                    "Rotation must be a multiple of 90 degrees, but was #{value}.")
+        end
+      when :darkness
+        unless value.is_a?(Numeric) && value.between?(0, 100)
+          raise ValidationError.new("darkness",
+                                    "Darkness must be between 0 and 100, but was #{value}.")
+        end
+      end
+      value.is_a?(Symbol) ? value.to_s : value
+    end
+
+    def nested(key, value, mapping)
+      unless value.is_a?(Hash)
+        raise ValidationError.new(key.to_s, "#{key} must be a Hash, but was #{describe(value)}.")
+      end
+
+      value.each_with_object({}) do |(nested_key, nested_value), out|
+        wire_key = mapping[nested_key.to_sym]
+        unless wire_key
+          raise ValidationError.new(key.to_s,
+                                    "#{key}[#{nested_key.inspect}] is not a recognized option. " \
+                                    "Expected one of: #{mapping.keys.join(", ")}.")
+        end
+        next if UNSET.equal?(nested_value)
+
+        out[wire_key] = nested_value.is_a?(Symbol) ? nested_value.to_s : nested_value
+      end
+    end
+
+    # +data+ is always an array -- one entry produces one label. A caller passing a single
+    # record means "one label", so a bare Hash is wrapped rather than rejected.
+    def normalize_data(value)
+      records = value.is_a?(Array) ? value : [value]
+
+      records.each_with_index.map do |record, index|
+        unless record.is_a?(Hash)
+          raise ValidationError.new("data",
+                                    "data[#{index}] is #{describe(record)}; every entry must be " \
+                                    "an object whose keys are the label's variable field names.")
+        end
+        stringify(record)
+      end
+    end
+
+    def stringify(hash)
+      unless hash.is_a?(Hash)
+        raise ValidationError.new("extra", "extra must be a Hash, but was #{describe(hash)}.")
+      end
+
+      hash.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+    end
+
+    def describe(value)
+      case value
+      when nil then "null"
+      when Array then "an array"
+      when String then "a string"
+      when Numeric then "a number"
+      when true, false then "a boolean"
+      else "a #{value.class}"
+      end
+    end
+  end
+end

data/lib/labelzoom/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LabelZoom
+  # The gem version. It appears in the User-Agent of every request, so the release
+  # workflow asserts that it matches the `ruby/vX.Y.Z` tag being published.
+  VERSION = "1.0.0"
+end

data/lib/labelzoom.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "labelzoom/version"
+require_relative "labelzoom/errors"
+require_relative "labelzoom/formats"
+require_relative "labelzoom/options"
+require_relative "labelzoom/conversion_result"
+require_relative "labelzoom/client"
+
+# Official Ruby client for the LabelZoom API.
+#
+# LabelZoom converts barcode labels between printer languages (ZPL, EPL, TSPL, DPL),
+# LabelZoom's own XML/JSON model, PDF, and raster images. Almost everything the API does
+# happens at one endpoint:
+#
+#     POST https://api.labelzoom.com/api/v2/convert/{sourceFormat}/to/{targetFormat}
+#
+#     client = LabelZoom::Client.new
+#     result = client.convert(:zpl, :png, "^XA^FO20,20^A0N,28^FDhello^FS^XZ",
+#                             label: { width: 4, height: 6 })
+#     result.save("label.png")
+#
+# The behaviour of every LabelZoom SDK is specified in docs/API_CONTRACT.md and checked by
+# the shared fixtures in conformance/, which this gem's spec suite executes.
+module LabelZoom
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: labelzoom
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- RJF Technology Solutions LLC
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Converts barcode labels between ZPL, EPL, TSPL, DPL, PDF, LabelZoom XML/JSON,
+  and raster images via the LabelZoom API.
+email:
+- support@labelzoom.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/labelzoom.rb
+- lib/labelzoom/client.rb
+- lib/labelzoom/conversion_result.rb
+- lib/labelzoom/errors.rb
+- lib/labelzoom/formats.rb
+- lib/labelzoom/options.rb
+- lib/labelzoom/version.rb
+homepage: https://www.labelzoom.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.labelzoom.com
+  source_code_uri: https://github.com/labelzoom/labelzoom-sdk
+  documentation_uri: https://docs.labelzoom.com
+  bug_tracker_uri: https://github.com/labelzoom/labelzoom-sdk/issues
+  changelog_uri: https://github.com/labelzoom/labelzoom-sdk/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the LabelZoom label conversion API.
+test_files: []