choiceqr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07dec0ce2e854c10973278cf04728e882f6402babed554baed28ad04760b267e
+  data.tar.gz: 138b5ff77c3bfe9b9113fddd791bc32fbee5d59abe4a3a949c3037e72f7ee410
+SHA512:
+  metadata.gz: 5214c6437aab17feab020cdd34046e8001406667efc3936f5d1469903a13da27723e11ed008778807a886768566d2de1ec1354b24f99759c470ef0eed38148e9
+  data.tar.gz: 33437df630e03f6718fd77d41df0e6fd5a195f81f4046fee2f18d9ea8f2f687bdc9b07590b8cc21e9709bb05efe083bcd744778e2e70e30993bcb46b227bac3a

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stockbird Team
+
+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,243 @@
+# choiceqr
+
+Ruby API client for the [ChoiceQR Open API](https://open-api.choiceqr.com/docs#/).
+
+Handles authentication and provides a clean interface to the place, menu, location, order, booking, and feedback resources. Built by [Stockbird](https://stockbird.app).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "choiceqr"
+```
+
+Or install directly:
+
+```sh
+gem install choiceqr
+```
+
+## Requirements
+
+- Ruby >= 3.3.0
+- A ChoiceQR application and access token obtained via the [ChoiceQR OAuth flow](https://open-api.choiceqr.com/docs/content/authorization) — contact api@choiceqr.com to register.
+
+## Quick start
+
+```ruby
+client = ChoiceQR::Client.new(token: ENV["CHOICEQR_TOKEN"])
+
+place = client.place.get
+puts place.name
+
+sections = client.sections.list
+sections.each { |section| puts section.name }
+```
+
+## Authentication
+
+ChoiceQR access tokens are obtained once via an OAuth-style authorization code flow and are valid for roughly five years — there is no refresh step to manage at runtime. Once you have the `code` from the "Ask permission" redirect, exchange it for a token:
+
+```ruby
+result = ChoiceQR::Client.exchange_token(code: code, client_id: client_id, secret: secret)
+result.token       # => access token, valid ~5 years — store this securely
+result.var_symbol  # => uniq company identifier
+result.domain      # => company domain
+
+client = ChoiceQR::Client.new(token: result.token)
+```
+
+See [Authorization](https://open-api.choiceqr.com/docs/content/authorization) for the full flow (connecting your application to a client, permission dialog, callback URL).
+
+## Resources
+
+The following resource accessors are available on the client:
+
+| Method | API path |
+|---|---|
+| `client.place` | `place` |
+| `client.section_info` | `menu/:language/section-info/:sectionId` |
+| `client.sections` | `menu/:language/sections` |
+| `client.categories` | `menu/:language/categories`, scoped by section |
+| `client.dishes` | `menu/:language/dishes`, scoped by category |
+| `client.dish_options` | `menu/:language/options`, scoped by section |
+| `client.dish_labels` | `menu/:language/dish-labels` |
+| `client.pack` | `menu/:language/pack` |
+| `client.cutlery` | `menu/:language/cutlery` (a single settings object, no id) |
+| `client.full_menu` | `menu/:language/full/*` — bulk import, availability sync, marketplace sync |
+| `client.areas` | `location/:language/areas` |
+| `client.location_points` | `location/:language/points`, scoped by area |
+| `client.orders` | `orders` |
+| `client.bookings` | `bookings` |
+| `client.feedbacks` | `feedbacks` |
+
+Most menu/location methods accept a per-call `language:` override; when omitted, the client's `default_language` (`"en"` unless configured otherwise) is used:
+
+```ruby
+client = ChoiceQR::Client.new(token: token, default_language: "de")
+client.sections.list                 # uses "de"
+client.sections.list(language: "cs") # overrides to "cs" for this call
+```
+
+## CRUD operations
+
+Attributes are passed as keyword arguments (or splat a Hash with `**`), not a positional Hash — this matches how most modern Ruby API clients read, and keeps every method's required path arguments (`id`, `section_id`, …) unambiguous from the optional attributes:
+
+```ruby
+section = client.sections.create(name: "Drinks", pos_id: "10")
+client.sections.update(section.id, name: "Beverages")
+client.sections.set_position([id1, id2, id3])
+client.sections.delete(section.id)
+
+category = client.categories.create(name: "Hot", section: section.id)
+client.categories.list(section.id)
+
+dish = client.dishes.create(name: "Cappuccino", category: category.id, price: 420) # price is in cents
+client.dishes.update(dish.id, name: "Double Espresso", price: 450)
+client.dishes.patch(dish.id, active: false) # partial update
+client.dishes.update_areas(dish.id, takeaway: true, delivery: false)
+client.dishes.find_by_pos_id("your-pos-id")
+```
+
+`update`/`patch`/position-bulk/attach/detach endpoints return `204 No Content` on success — the corresponding gem methods return `true` rather than a fetched Resource (there's no ETag or similar concurrency token to round-trip). `delete` also returns `true`.
+
+### Full menu import and availability sync
+
+```ruby
+client.full_menu.import(
+  sections: [{ pos_id: "1", name: "Main" }],
+  categories: [{ pos_id: "1", section_pos_id: "1", name: "Hot" }],
+  dishes: [{ pos_id: "1", category_pos_id: "1", name: "Coffee", price: 300 }],
+  preserve_missing_items: true
+)
+
+client.full_menu.sync_availability(dishes: [{ pos_id: "525", active: false }])
+
+sync = client.full_menu.sync_marketplace_data(
+  dishes: [{ pos_id: "1", data: { WOLT: { price: 1000, name: "Wolt name" } } }]
+)
+client.full_menu.marketplace_sync_status(sync.id)
+```
+
+### Orders
+
+```ruby
+client.orders.list(since: Time.now - 3600, include_approved: true)
+client.orders.list_archive(from: Time.now - 86_400 * 30, till: Time.now) # rate limit: 1 req / 5s
+order = client.orders.get(id)
+client.orders.get_by_guid(order.guid)
+client.orders.update_delivery(order.id, delivery_status: "processing")
+client.orders.cancel(order.id, reason: "Out of stock")
+client.orders.close(order.id)
+```
+
+### Bookings
+
+```ruby
+client.bookings.list(from: Time.now, till: Time.now + 86_400 * 7) # rate limit: 1 req / 5s
+booking = client.bookings.get(id)
+client.bookings.confirm(booking.id, location_points: [point_id])
+client.bookings.cancel(booking.id, cancel_reason: "Table no longer available")
+```
+
+### Feedbacks
+
+```ruby
+client.feedbacks.list(type: "ORDER")
+client.feedbacks.create(
+  ref_id: order_id,
+  feedback: { type: "ORDER", rate_serve: 5, rate_dish: 4, language: "en", message: "Great!" },
+  customer: { name: "John Doe", phone: "+380501234567" }
+) # rate limit: 1 req / 10s
+```
+
+## Response objects
+
+All returned data is a `ChoiceQR::Resource` — a generic object backed by a snake_case symbol-keyed hash. Nested data (menu options, order items, etc.) is wrapped the same way at every depth, so dot access works throughout:
+
+```ruby
+dish.name                              # dot notation
+dish[:name]                            # symbol key
+dish["posID"]                          # camelCase string key (also works)
+dish.menu_options.first.list.first.price
+dish.to_h                              # plain hash, nested Resources unwrapped
+```
+
+API keys are transformed as follows:
+- `defaultLanguage` → `:default_language`
+- `posID` → `:pos_id` (the one field ChoiceQR capitalizes as an acronym instead of plain camelCase)
+- `_id` → `:id` (leading underscore stripped)
+
+A field whose name collides with a real `Object` method (`hash`, `method`, `class`, `send`, …) isn't reachable via dot access — Ruby dispatches to the real method first. Use `resource[:hash]`-style hash access for those instead.
+
+## Error handling
+
+All errors inherit from `ChoiceQR::Error` and carry `http_status`, `http_body`, `http_headers`, and `error_name` (the API's own `"ValidationError"`/`"ServiceError"` classification, where present):
+
+```ruby
+begin
+  client.dishes.get("nonexistent")
+rescue ChoiceQR::NotFoundError
+  # unknown id
+rescue ChoiceQR::AuthenticationError
+  # token missing or invalid
+rescue ChoiceQR::ForbiddenError
+  # token doesn't have the required scope
+rescue ChoiceQR::ValidationError => e
+  puts e.message
+rescue ChoiceQR::RateLimitError
+  # 429 — the gem already retries a couple of times with backoff before this is raised
+rescue ChoiceQR::ServerError
+  # 5xx
+rescue ChoiceQR::Error => e
+  # catch-all
+end
+```
+
+Full error hierarchy:
+
+```
+ChoiceQR::Error
+├── ChoiceQR::ConnectionError
+├── ChoiceQR::TimeoutError
+└── ChoiceQR::ClientError
+    ├── ChoiceQR::ValidationError      (400)
+    ├── ChoiceQR::AuthenticationError  (401)
+    ├── ChoiceQR::ForbiddenError       (403)
+    ├── ChoiceQR::NotFoundError        (404)
+    └── ChoiceQR::RateLimitError       (429)
+└── ChoiceQR::ServerError              (5xx)
+```
+
+## Rate limits
+
+The API documents a general 60 req/sec limit, with some endpoints stricter still (booking/order-archive listing, feedback creation, availability/marketplace sync — see the relevant method's docs above). The gem automatically retries a request up to twice with backoff on `429`/`5xx` responses; persistent rate limiting still raises `ChoiceQR::RateLimitError`. The gem does not otherwise throttle requests client-side — back off in your own code if you're making high-volume calls.
+
+## Configuration
+
+```ruby
+client = ChoiceQR::Client.new(
+  token: "...",
+  default_language: "en", # default: "en"
+  timeout: 60,             # read timeout in seconds (default: 30)
+  open_timeout: 10,        # connection timeout in seconds (default: 5)
+  logger: Logger.new($stdout)
+)
+```
+
+## Webhooks
+
+ChoiceQR pushes events (menu changes, new orders, booking updates, …) to a Webhook URL you configure when creating your application — there is no API for managing webhook subscriptions, so this gem does not include a webhook client. See [Webhooks](https://open-api.choiceqr.com/docs/content/webhooks) for the event payload shape; the `data` field of each event matches the corresponding resource's response schema, so you can wrap it yourself with `ChoiceQR::Resource.new(event["data"])` if useful.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

data/lib/choiceqr/client.rb

@@ -0,0 +1,248 @@
+require "faraday"
+require "faraday/retry"
+require "json"
+require "securerandom"
+
+module ChoiceQR
+  # Entry point for all API interactions.
+  #
+  # Usage:
+  #   client = ChoiceQR::Client.new(token: "your_token")
+  #
+  #   place = client.place.get
+  #   sections = client.sections.list
+  #   client.dishes.create(name: "Cappuccino", category: category_id, price: 420)
+  #
+  #   # Most menu/location endpoints accept a per-call language override; the
+  #   # client's default_language ("en" unless configured otherwise) is used
+  #   # when omitted.
+  #   client.sections.list(language: "de")
+  #
+  # See ChoiceQR::Client.exchange_token for obtaining a +token+ in the first
+  # place, and https://open-api.choiceqr.com/docs/content/authorization for
+  # the full OAuth flow.
+  class Client
+    API_BASE_URL = "https://open-api.choiceqr.com/".freeze
+
+    # Maps HTTP error status codes to [ErrorClass, default_message] pairs.
+    ERROR_MAP = {
+      400 => [ValidationError, "Bad request"],
+      401 => [AuthenticationError, "Missing or invalid token"],
+      403 => [ForbiddenError, "Insufficient rights"],
+      404 => [NotFoundError, "Resource not found"],
+      429 => [RateLimitError, "Rate limit exceeded"],
+    }.freeze
+
+    attr_reader :default_language
+
+    # @param token           [String]  long-lived access token obtained via the OAuth flow
+    #                                  (see .exchange_token). Valid for ~5 years.
+    # @param default_language [String] default :language path segment for menu/location calls
+    # @param timeout          [Integer] read timeout in seconds
+    # @param open_timeout     [Integer] connection timeout in seconds
+    # @param logger           [Logger, nil] optional logger; receives request/response details
+    #
+    # +default_language+/+timeout+/+open_timeout+/+logger+ each default to the
+    # matching value on +ChoiceQR.configuration+ (see ChoiceQR.configure).
+    def initialize(token:, default_language: ChoiceQR.configuration.default_language,
+                   timeout: ChoiceQR.configuration.timeout, open_timeout: ChoiceQR.configuration.open_timeout,
+                   logger: ChoiceQR.configuration.logger)
+      @token             = token
+      @default_language  = default_language.to_s
+      @timeout           = timeout
+      @open_timeout      = open_timeout
+      @logger            = logger
+    end
+
+    def place
+      @place ||= Resources::Place.new(self)
+    end
+
+    def section_info
+      @section_info ||= Resources::SectionInfo.new(self)
+    end
+
+    def sections
+      @sections ||= Resources::Sections.new(self)
+    end
+
+    def categories
+      @categories ||= Resources::Categories.new(self)
+    end
+
+    def dishes
+      @dishes ||= Resources::Dishes.new(self)
+    end
+
+    def dish_options
+      @dish_options ||= Resources::DishOptions.new(self)
+    end
+
+    def dish_labels
+      @dish_labels ||= Resources::DishLabels.new(self)
+    end
+
+    def pack
+      @pack ||= Resources::Pack.new(self)
+    end
+
+    def cutlery
+      @cutlery ||= Resources::Cutlery.new(self)
+    end
+
+    def full_menu
+      @full_menu ||= Resources::FullMenu.new(self)
+    end
+
+    def areas
+      @areas ||= Resources::Areas.new(self)
+    end
+
+    def location_points
+      @location_points ||= Resources::LocationPoints.new(self)
+    end
+
+    def orders
+      @orders ||= Resources::Orders.new(self)
+    end
+
+    def bookings
+      @bookings ||= Resources::Bookings.new(self)
+    end
+
+    def feedbacks
+      @feedbacks ||= Resources::Feedbacks.new(self)
+    end
+
+    # Exchanges the authorization +code+ obtained from the "Ask permission"
+    # redirect for a long-lived access token. This is a one-time setup step;
+    # store the returned token and pass it to .new as +token:+.
+    #
+    #   result = ChoiceQR::Client.exchange_token(code: code, client_id: client_id, secret: secret)
+    #   result.token       # => access token, valid ~5 years
+    #   result.var_symbol  # => uniq company identifier
+    #   result.domain      # => company domain
+    #
+    # See https://open-api.choiceqr.com/docs/content/authorization
+    def self.exchange_token(code:, client_id:, secret:,
+                            timeout: ChoiceQR.configuration.timeout,
+                            open_timeout: ChoiceQR.configuration.open_timeout)
+      response = post_token_request(code: code, client_id: client_id, secret: secret,
+                                    timeout: timeout, open_timeout: open_timeout)
+      body = parse_response_body(response.body)
+
+      return Resource.new(body) if response.success?
+
+      raise_error_for(response, body)
+    end
+
+    # Makes an authenticated HTTP request. Used internally by the resource
+    # wrapper classes (client.sections, client.orders, …).
+    #
+    # @param method  [Symbol]  :get, :post, :put, :patch, :delete
+    # @param path    [String]  path relative to API_BASE_URL (e.g. "menu/en/sections/list")
+    # @param params  [Hash]    query parameters
+    # @param body    [Hash, Array, nil] request body (will be JSON-encoded)
+    # @param headers [Hash]    additional request headers
+    # @return [Hash] { body: parsed_response }
+    def request(method, path, params: {}, body: nil, headers: {})
+      response = execute_request(method, path, params: params, body: body, headers: headers)
+      handle_response(response)
+    end
+
+    private
+
+    def execute_request(method, path, params:, body:, headers:)
+      connection.run_request(method, path, body&.to_json, request_headers(headers)) do |req|
+        req.params = params unless params.empty?
+      end
+    rescue Faraday::ConnectionFailed => e
+      raise ChoiceQR::ConnectionError, e.message
+    rescue Faraday::TimeoutError => e
+      raise ChoiceQR::TimeoutError, e.message
+    end
+
+    def handle_response(response)
+      body = self.class.send(:parse_response_body, response.body)
+
+      return { body: body } if (200..299).cover?(response.status)
+
+      self.class.send(:raise_error_for, response, body)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: API_BASE_URL) do |f|
+        f.options.timeout      = @timeout
+        f.options.open_timeout = @open_timeout
+        # The API documents a 60 req/sec rate limit (some endpoints are
+        # stricter — see individual resource methods) and returns 429 when
+        # exceeded; back off and retry a couple of times before giving up.
+        f.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                          retry_statuses: [429, 500, 502, 503, 504],
+                          exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS
+        f.request :logger, @logger, headers: false, bodies: false if @logger
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request_headers(extra = {})
+      {
+        "Authorization" => "Bearer #{@token}",
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        # Lets the API de-duplicate a request that is retried after a
+        # network/timeout issue instead of processing it twice.
+        "x-idempotence-key" => SecureRandom.uuid,
+        "User-Agent" => "choiceqr-ruby/#{ChoiceQR::VERSION} ruby/#{RUBY_VERSION}",
+      }.merge(extra)
+    end
+
+    class << self
+      private
+
+      def post_token_request(code:, client_id:, secret:, timeout:, open_timeout:)
+        connection = Faraday.new(url: API_BASE_URL) do |f|
+          f.options.timeout      = timeout
+          f.options.open_timeout = open_timeout
+          f.adapter Faraday.default_adapter
+        end
+
+        connection.post("auth/connect/token") do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(code: code, clientId: client_id, secret: secret)
+        end
+      end
+
+      # Shared by both the class-level .exchange_token and instance-level
+      # #request — the two entry points that talk to the API before/without
+      # going through the same instance.
+      def parse_response_body(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body, symbolize_names: false)
+      rescue JSON::ParserError
+        body
+      end
+
+      def raise_error_for(response, body)
+        klass, default_msg = ERROR_MAP[response.status]
+        klass       ||= response.status >= 500 ? ServerError : Error
+        default_msg ||= response.status >= 500 ? "Server error" : "Unexpected status #{response.status}"
+
+        raise klass.new(
+          error_message(body, default_msg),
+          http_status: response.status,
+          http_body: response.body,
+          http_headers: response.headers,
+          error_name: body.is_a?(Hash) ? body["name"] : nil
+        )
+      end
+
+      def error_message(parsed_body, fallback)
+        return fallback unless parsed_body.is_a?(Hash)
+
+        parsed_body["message"] || fallback
+      end
+    end
+  end
+end

data/lib/choiceqr/configuration.rb

@@ -0,0 +1,14 @@
+module ChoiceQR
+  class Configuration
+    attr_accessor :timeout, :open_timeout, :logger, :default_language
+
+    API_BASE_URL = "https://open-api.choiceqr.com/".freeze
+
+    def initialize
+      @timeout          = 30
+      @open_timeout     = 5
+      @logger           = nil
+      @default_language = "en"
+    end
+  end
+end

data/lib/choiceqr/errors.rb

@@ -0,0 +1,38 @@
+module ChoiceQR
+  # Base error — callers can rescue ChoiceQR::Error to catch everything.
+  class Error < StandardError
+    attr_reader :http_status, :http_body, :http_headers, :error_name
+
+    def initialize(msg = nil, http_status: nil, http_body: nil, http_headers: nil, error_name: nil)
+      super(msg)
+      @http_status  = http_status
+      @http_body    = http_body
+      @http_headers = http_headers
+      @error_name   = error_name
+    end
+
+    def to_s
+      http_status ? "(HTTP #{http_status}) #{super}" : super
+    end
+  end
+
+  # Network-level errors
+  class ConnectionError < Error; end
+  class TimeoutError    < Error; end
+
+  # 4xx client errors
+  class ClientError         < Error; end
+  # 400 — the API calls this "ValidationError" or "ServiceError"
+  class ValidationError     < ClientError; end
+  # 401 — missing or invalid token
+  class AuthenticationError < ClientError; end
+  # 403 — token does not have the required scope/rights
+  class ForbiddenError      < ClientError; end
+  # 404 — not documented in the API guidelines, but returned for unknown IDs
+  class NotFoundError       < ClientError; end
+  # 429
+  class RateLimitError      < ClientError; end
+
+  # 5xx server errors
+  class ServerError < Error; end
+end

data/lib/choiceqr/key_transformer.rb

@@ -0,0 +1,105 @@
+module ChoiceQR
+  # Bidirectional key transformation between the API's lowerCamelCase format
+  # and Ruby's conventional snake_case.
+  #
+  # API → Ruby (responses):
+  #   "defaultLanguage" → :default_language
+  #   "posID"           → :pos_id
+  #   "sectionPosID"    → :section_pos_id
+  #   "_id"             → :id   (leading underscore stripped)
+  #
+  # Ruby → API (request bodies):
+  #   :default_language → "defaultLanguage"
+  #   :pos_id            → "posID"           (see #merge_acronyms below)
+  #   :section_pos_id     → "sectionPosID"
+  #   :_id                → "_id"    (a leading underscore is preserved, since
+  #                                    some payloads reference an existing
+  #                                    entity's id this way, e.g. Pack#create
+  #                                    categories)
+  #
+  # Note: "PosID" is the one acronym the ChoiceQR API capitalizes in full
+  # instead of following plain camelCase ("Id") — and it shows up both as a
+  # standalone field and as a suffix on cross-reference fields (sectionPosID,
+  # categoryPosID, …) throughout the whole API, so #camelize special-cases
+  # the "pos"+"id" word pair wherever it appears rather than only matching
+  # the exact key "posID"/"pos_id".
+  module KeyTransformer
+    module_function
+
+    # Recursively transforms all keys in a Hash (or Array of Hashes) from the
+    # API format to snake_case symbols.
+    def to_snake(obj)
+      case obj
+      when Hash
+        obj.transform_keys { |k| snake_key(k) }
+           .transform_values { |v| to_snake(v) }
+      when Array
+        obj.map { |v| to_snake(v) }
+      else
+        obj
+      end
+    end
+
+    # Recursively transforms all keys in a Hash (or Array of Hashes) from
+    # snake_case symbols/strings to lowerCamelCase strings for API requests.
+    def to_camel(obj)
+      case obj
+      when Hash
+        obj.transform_keys { |k| camel_key(k) }
+           .transform_values { |v| to_camel(v) }
+      when Array
+        obj.map { |v| to_camel(v) }
+      else
+        obj
+      end
+    end
+
+    # Single key: API string → snake_case symbol
+    def snake_key(key)
+      key.to_s
+         .delete_prefix("_") # strip leading underscore (_id → id)
+         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2') # ABCDef → ABC_def
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2') # camelCase → camel_case
+         .downcase
+         .to_sym
+    end
+
+    # Single key: snake_case symbol/string → lowerCamelCase string
+    def camel_key(key)
+      str    = key.to_s
+      prefix = str.start_with?("_") ? "_" : ""
+      body   = prefix.empty? ? str : str[1..]
+
+      prefix + camelize(body)
+    end
+
+    def camelize(str)
+      segments = merge_acronyms(str.split("_"))
+      return "" if segments.empty? # e.g. an all-underscore key like :_ or :__
+
+      segments[0] + segments[1..].join
+    end
+
+    # Joins an adjacent ["pos", "id"] word pair into the API's "posID"/"PosID"
+    # acronym spelling instead of capitalizing them individually into
+    # "posId"/"PosId". Every other word is capitalized normally, except the
+    # very first segment of the key, which is used verbatim (standard
+    # camelCase, and how a single-word key like :WOLT survives untouched).
+    def merge_acronyms(parts)
+      segments = []
+      i = 0
+      while i < parts.length
+        acronym = parts[i] == "pos" && parts[i + 1] == "id"
+        segments << next_segment(parts[i], first: segments.empty?, acronym: acronym)
+        i += acronym ? 2 : 1
+      end
+      segments
+    end
+
+    def next_segment(word, first:, acronym:)
+      return first ? "posID" : "PosID" if acronym
+
+      first ? word : word.capitalize
+    end
+  end
+end