dotypos 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a64ec820b14432a4f7f5846c0a27688e081eedd352be2e881173a27a9a1fbba
+  data.tar.gz: 8e3d6f7d7e4cddc4d9256ef7b40aef688ac63376807d92c35d86ee47da9907c8
+SHA512:
+  metadata.gz: 48174bfed7b8afc5932c3ec2a88b608dc5734e583d86f0524d744582fc395f435bbe5628b68837ad70161905f9b834924a48a8d4598b1836460aa6d1d41f7b00
+  data.tar.gz: 7c0bc07e13990cd02c5c92d6ee1ec8db3c347bc55c37dd0fa1a28329f6ceb970dbc7f77fa6f28b483b3fd5b291a6f32fcb2fbff09a274eaf24e99e2e51a4cf04

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,232 @@
+# dotypos
+
+Ruby API client for the [Dotypos (Dotykačka) API v2](https://docs.api.dotypos.com/).
+
+Handles OAuth token management, automatic token refresh, pagination, and full CRUD for all API resources. Built by [Stockbird](https://stockbird.app).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "dotypos"
+```
+
+Or install directly:
+
+```sh
+gem install dotypos
+```
+
+## Requirements
+
+- Ruby >= 3.3.0
+- A Dotypos `refresh_token` and `cloud_id` obtained via the [Dotypos OAuth flow](https://docs.api.dotypos.com/)
+
+## Quick start
+
+```ruby
+client = Dotypos::Client.new(
+  refresh_token: ENV["DOTYPOS_REFRESH_TOKEN"],
+  cloud_id:      ENV["DOTYPOS_CLOUD_ID"]
+)
+
+# List orders (returns a PagedResult)
+result = client.orders.list(limit: 25)
+result.data.each { |order| puts "#{order.id}: #{order.note}" }
+
+# Paginate
+while result.next_page?
+  result = result.next_page
+  result.data.each { |order| puts order.id }
+end
+```
+
+## Authentication
+
+The gem handles authentication automatically. You only need to supply a `refresh_token` and `cloud_id` once — the gem obtains a short-lived access token and refreshes it transparently before it expires (~1 hour). The access token is kept in memory; no persistence is needed.
+
+## Resources
+
+The following resource accessors are available on the client:
+
+| Method | API path |
+|---|---|
+| `client.branches` | `branch` |
+| `client.categories` | `category` |
+| `client.courses` | `course` |
+| `client.customers` | `customer` |
+| `client.employees` | `employee` |
+| `client.order_items` | `order-item` |
+| `client.orders` | `order` |
+| `client.points_logs` | `pointslog` |
+| `client.printers` | `printer` |
+| `client.products` | `product` |
+| `client.reservations` | `reservation` |
+| `client.stock_logs` | `stocklog` |
+| `client.suppliers` | `supplier` |
+| `client.tags` | `tag` |
+| `client.warehouses` | `warehouse` |
+| `client.webhooks` | `webhook` |
+
+For any path not in the list above:
+
+```ruby
+client.resource("custom-entity").list
+```
+
+## CRUD operations
+
+### List
+
+```ruby
+result = client.products.list(page: 1, limit: 50, sort: "-versionDate")
+result.data          # => [Dotypos::Resource, ...]
+result.current_page  # => 1
+result.next_page?    # => true
+result.next_page     # => PagedResult for page 2
+result.prev_page?    # => false
+```
+
+### Filter DSL
+
+```ruby
+filter = Dotypos::FilterBuilder.build do |f|
+  f.where :deleted,     :eq,   false
+  f.where :total_price, :gteq, 100
+  f.where :name,        :like, "coffee"
+end
+
+result = client.products.list(filter: filter, sort: "-version_date")
+```
+
+Supported operators: `eq`, `ne`, `gt`, `gteq`, `lt`, `lteq`, `like`, `in`, `notin`, `bin`, `bex`.
+
+### Get single resource
+
+```ruby
+product = client.products.get("123456789")
+product.name          # => "Espresso"
+product.total_price   # => "3.50"
+product.etag          # => '"5C6FEF0BAD91914172B353E157219626"' (for updates)
+product[:name]        # hash-style access
+product.to_h          # plain snake_case symbol-keyed hash
+```
+
+### Create
+
+```ruby
+product = client.products.create(
+  name:        "Cappuccino",
+  total_price: "4.20"
+)
+
+# Batch create
+products = client.products.create([
+  { name: "Espresso", total_price: "3.50" },
+  { name: "Latte",    total_price: "4.80" }
+])
+```
+
+### Update (PATCH)
+
+Always fetch first to get the ETag, then update:
+
+```ruby
+product = client.products.get("123456789")
+updated = client.products.update(product, name: "Double Espresso")
+
+# Or with explicit ID + ETag:
+updated = client.products.update("123456789", { name: "Double Espresso" }, etag: product.etag)
+```
+
+### Replace (PUT)
+
+```ruby
+product = client.products.get("123456789")
+replaced = client.products.replace(product, product.to_h.merge(name: "New Name"))
+```
+
+### Delete
+
+```ruby
+client.products.delete("123456789")  # => true
+```
+
+## Response objects
+
+All returned data is a `Dotypos::Resource` — a generic object backed by a snake_case symbol-keyed hash. Access attributes via dot notation, hash notation, or `to_h`:
+
+```ruby
+order.total_price     # dot notation
+order[:total_price]   # symbol key
+order["totalPrice"]   # camelCase string key (also works)
+order.to_h            # plain hash
+```
+
+API keys are transformed as follows:
+- `currentPage` → `:current_page`
+- `_cloudId` → `:cloud_id` (leading underscore stripped)
+- `totalItemsCount` → `:total_items_count`
+
+## Error handling
+
+All errors inherit from `Dotypos::Error` and carry `http_status`, `http_body`, and `http_headers`:
+
+```ruby
+begin
+  client.orders.get("nonexistent")
+rescue Dotypos::NotFoundError => e
+  puts e.http_status  # 404
+rescue Dotypos::AuthenticationError
+  # refresh_token invalid or revoked
+rescue Dotypos::PreconditionError
+  # ETag mismatch — resource was modified since last GET
+rescue Dotypos::RateLimitError
+  # 429 — back off and retry
+rescue Dotypos::ServerError
+  # 5xx
+rescue Dotypos::Error => e
+  # catch-all
+end
+```
+
+Full error hierarchy:
+
+```
+Dotypos::Error
+├── Dotypos::ConnectionError
+├── Dotypos::TimeoutError
+└── Dotypos::ClientError
+    ├── Dotypos::AuthenticationError   (401)
+    ├── Dotypos::ForbiddenError        (403)
+    ├── Dotypos::NotFoundError         (404)
+    ├── Dotypos::ConflictError         (409)
+    ├── Dotypos::PreconditionError     (412)
+    ├── Dotypos::UnprocessableError    (422)
+    └── Dotypos::RateLimitError        (429)
+└── Dotypos::ServerError               (5xx)
+```
+
+## Configuration
+
+```ruby
+client = Dotypos::Client.new(
+  refresh_token: "...",
+  cloud_id:      "...",
+  timeout:       60,    # read timeout in seconds (default: 30)
+  open_timeout:  10,    # connection timeout in seconds (default: 5)
+  logger:        Logger.new($stdout)
+)
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

data/lib/dotypos/client.rb

@@ -0,0 +1,189 @@
+require "faraday"
+require "json"
+
+module Dotypos
+  # Entry point for all API interactions.
+  #
+  # Usage:
+  #   client = Dotypos::Client.new(
+  #     refresh_token: "your_refresh_token",
+  #     cloud_id:      "123456"
+  #   )
+  #
+  #   # List resources
+  #   result = client.orders.list(page: 1, limit: 25)
+  #   result.data.each { |order| puts order.id }
+  #
+  #   # Paginate
+  #   next_result = result.next_page if result.next_page?
+  #
+  #   # Filter with DSL
+  #   filter = Dotypos::FilterBuilder.build { |f| f.where(:deleted, :eq, false) }
+  #   client.products.list(filter: filter, sort: "-version_date")
+  #
+  #   # Full CRUD
+  #   customer = client.customers.get("789")
+  #   client.customers.update(customer, name: "New Name")
+  class Client
+    API_BASE_URL = "https://api.dotykacka.cz/v2/".freeze
+
+    # All supported resource types.
+    # key   = Ruby method name (snake_case, plural)
+    # value = API path segment (as used in /v2/clouds/:cloudId/<segment>)
+    RESOURCES = {
+      branches: "branch",
+      categories: "category",
+      courses: "course",
+      customers: "customer",
+      employees: "employee",
+      order_items: "order-item",
+      orders: "order",
+      points_logs: "pointslog",
+      printers: "printer",
+      products: "product",
+      reservations: "reservation",
+      stock_logs: "stocklog",
+      suppliers: "supplier",
+      tags: "tag",
+      warehouses: "warehouse",
+      webhooks: "webhook",
+    }.freeze
+
+    # Maps HTTP error status codes to [ErrorClass, default_message] pairs.
+    ERROR_MAP = {
+      401 => [AuthenticationError, "Authentication failed"],
+      403 => [ForbiddenError, "Forbidden"],
+      404 => [NotFoundError, "Resource not found"],
+      409 => [ConflictError, "Conflict — versionDate mismatch"],
+      412 => [PreconditionError, "ETag mismatch — resource was modified since last read"],
+      422 => [UnprocessableError, "Unprocessable entity"],
+      429 => [RateLimitError, "Rate limit exceeded"],
+    }.freeze
+
+    attr_reader :cloud_id
+
+    # @param refresh_token [String]  long-lived token obtained via the Dotypos OAuth flow
+    # @param cloud_id      [String]  cloud identifier for this installation
+    # @param timeout       [Integer] read timeout in seconds (default: 30)
+    # @param open_timeout  [Integer] connection timeout in seconds (default: 5)
+    # @param logger        [Logger, nil] optional logger; receives request/response details
+    def initialize(refresh_token:, cloud_id:, timeout: 30, open_timeout: 5, logger: nil)
+      @cloud_id      = cloud_id.to_s
+      @timeout       = timeout
+      @open_timeout  = open_timeout
+      @logger        = logger
+      @token_manager = build_token_manager(refresh_token, timeout, open_timeout)
+    end
+
+    # Dynamically define accessor methods for each resource type.
+    RESOURCES.each do |method_name, path|
+      define_method(method_name) { ResourceCollection.new(self, path) }
+    end
+
+    # Allows calling any arbitrary API path not in the RESOURCES list.
+    #   client.resource("custom-entity").list
+    def resource(path)
+      ResourceCollection.new(self, path)
+    end
+
+    # Makes an authenticated HTTP request. Used internally by ResourceCollection.
+    #
+    # @param method  [Symbol]  :get, :post, :patch, :put, :delete
+    # @param path    [String]  path relative to API_BASE_URL (e.g. "clouds/123/order")
+    # @param params  [Hash]    query parameters
+    # @param body    [Hash, nil] request body (will be JSON-encoded)
+    # @param headers [Hash]    additional request headers
+    # @return [Hash] { body: parsed_response, etag: "..." }
+    def request(method, path, params: {}, body: nil, headers: {})
+      response = execute_with_token_refresh(method, path, params: params, body: body, headers: headers)
+      handle_response(response)
+    end
+
+    private
+
+    def build_token_manager(refresh_token, timeout, open_timeout)
+      TokenManager.new(
+        refresh_token: refresh_token,
+        cloud_id: @cloud_id,
+        base_url: API_BASE_URL,
+        timeout: timeout,
+        open_timeout: open_timeout
+      )
+    end
+
+    def execute_with_token_refresh(method, path, params:, body:, headers:)
+      token    = @token_manager.access_token
+      response = execute_request(method, path, params: params, body: body, headers: headers, token: token)
+      return response unless response.status == 401
+
+      # Transparently retry once (token may have been invalidated server-side)
+      execute_request(method, path, params: params, body: body, headers: headers,
+                                    token: @token_manager.force_refresh!)
+    end
+
+    def execute_request(method, path, params:, body:, headers:, token:) # rubocop:disable Metrics/ParameterLists
+      connection.run_request(method, path, body&.to_json, request_headers(token, headers)) do |req|
+        req.params = params unless params.empty?
+      end
+    rescue Faraday::ConnectionFailed => e
+      raise Dotypos::ConnectionError, e.message
+    rescue Faraday::TimeoutError => e
+      raise Dotypos::TimeoutError, e.message
+    end
+
+    def handle_response(response)
+      body = parse_body(response.body)
+      etag = response.headers["etag"] || response.headers["ETag"]
+
+      return { body: body, etag: etag } if (200..299).cover?(response.status)
+      return { body: nil, etag: etag }  if response.status == 304
+
+      raise_error_for(response, 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
+      )
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: API_BASE_URL) do |f|
+        f.options.timeout      = @timeout
+        f.options.open_timeout = @open_timeout
+        f.request :logger, @logger, headers: false, bodies: false if @logger
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request_headers(token, extra = {})
+      {
+        "Authorization" => "Bearer #{token}",
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "dotypos-ruby/#{Dotypos::VERSION} ruby/#{RUBY_VERSION}",
+      }.merge(extra)
+    end
+
+    def parse_body(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body, symbolize_names: false)
+    rescue JSON::ParserError
+      body
+    end
+
+    def error_message(parsed_body, fallback)
+      return fallback unless parsed_body.is_a?(Hash)
+
+      parsed_body["message"] || parsed_body["error"] || fallback
+    end
+  end
+end

data/lib/dotypos/configuration.rb

@@ -0,0 +1,13 @@
+module Dotypos
+  class Configuration
+    attr_accessor :timeout, :open_timeout, :logger
+
+    API_BASE_URL = "https://api.dotykacka.cz/v2".freeze
+
+    def initialize
+      @timeout      = 30
+      @open_timeout = 5
+      @logger       = nil
+    end
+  end
+end

data/lib/dotypos/errors.rb

@@ -0,0 +1,41 @@
+module Dotypos
+  # Base error — callers can rescue Dotypos::Error to catch everything
+  class Error < StandardError
+    attr_reader :http_status, :http_body, :http_headers
+
+    def initialize(msg = nil, http_status: nil, http_body: nil, http_headers: nil)
+      super(msg)
+      @http_status  = http_status
+      @http_body    = http_body
+      @http_headers = http_headers
+    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
+  # 401
+  class AuthenticationError < ClientError; end
+  # 403
+  class ForbiddenError      < ClientError; end
+  # 404
+  class NotFoundError       < ClientError; end
+  # 409 — versionDate mismatch
+  class ConflictError       < ClientError; end
+  # 412 — ETag mismatch on PUT/PATCH
+  class PreconditionError   < ClientError; end
+  # 422
+  class UnprocessableError  < ClientError; end
+  # 429
+  class RateLimitError      < ClientError; end
+
+  # 5xx server errors
+  class ServerError < Error; end
+end

data/lib/dotypos/filter_builder.rb

@@ -0,0 +1,77 @@
+module Dotypos
+  # Builds the filter query string expected by the Dotypos API.
+  #
+  # API format:  "attribute|operator|value;attribute2|operator2|value2"
+  # Supported operators: eq, ne, gt, gteq, lt, lteq, like, in, notin, bin, bex
+  #
+  # Usage (block DSL):
+  #   filter = Dotypos::FilterBuilder.build do |f|
+  #     f.where :price,   :gteq,  500
+  #     f.where :deleted, :eq,    false
+  #     f.where :name,    :like,  "John"
+  #   end
+  #   # => "price|gteq|500;deleted|eq|0;name|like|John"
+  #
+  # Usage (chainable):
+  #   filter = Dotypos::FilterBuilder.new
+  #     .where(:price, :gteq, 500)
+  #     .where(:deleted, :eq, false)
+  #     .to_s
+  #
+  # Pass the result to any list call:
+  #   client.orders.list(filter: filter, sort: "-created")
+  class FilterBuilder
+    VALID_OPERATORS = %w[eq ne gt gteq lt lteq like in notin bin bex].freeze
+
+    def self.build(&block)
+      builder = new
+      block.call(builder)
+      builder.to_s
+    end
+
+    def initialize
+      @conditions = []
+    end
+
+    # Adds a filter condition.
+    #
+    # @param attribute [Symbol, String] the API attribute name (snake_case is converted to camelCase)
+    # @param operator  [Symbol, String] one of the supported operators
+    # @param value     the filter value (booleans are converted to 1/0)
+    # @return [self] for chaining
+    def where(attribute, operator, value)
+      op = operator.to_s.downcase
+      unless VALID_OPERATORS.include?(op)
+        raise ArgumentError, "Invalid filter operator '#{op}'. " \
+                             "Valid operators: #{VALID_OPERATORS.join(', ')}"
+      end
+
+      api_attribute = KeyTransformer.camel_key(attribute)
+      api_value     = serialize_value(value)
+
+      @conditions << "#{api_attribute}|#{op}|#{api_value}"
+      self
+    end
+
+    # Returns the encoded filter string or nil if no conditions were added.
+    def to_s
+      @conditions.empty? ? nil : @conditions.join(";")
+    end
+
+    def empty?
+      @conditions.empty?
+    end
+
+    private
+
+    def serialize_value(value)
+      case value
+      when true  then "1"
+      when false then "0"
+      when nil   then "null"
+      when Array then value.map { |v| serialize_value(v) }.join(",")
+      else value.to_s
+      end
+    end
+  end
+end

data/lib/dotypos/key_transformer.rb

@@ -0,0 +1,64 @@
+module Dotypos
+  # Bidirectional key transformation between the API's lowerCamelCase / _prefixed
+  # format and Ruby's conventional snake_case.
+  #
+  # API → Ruby (responses):
+  #   "currentPage"  → :current_page
+  #   "_cloudId"     → :cloud_id   (leading underscore stripped)
+  #   "totalItemsCount" → :total_items_count
+  #
+  # Ruby → API (request bodies):
+  #   :current_page      → "currentPage"
+  #   :cloud_id          → "cloudId"   (no underscore prefix re-added; see note below)
+  #
+  # Note: The API's _-prefixed keys (like _cloudId) appear in entity bodies as
+  # read-only metadata fields. When writing, cloudId is supplied via the URL path,
+  # not the request body, so the round-trip loss of the leading _ is harmless.
+  module KeyTransformer
+    module_function
+
+    # Recursively transform 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 transform 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 (_cloudId → cloudId)
+         .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)
+      parts = key.to_s.split("_")
+      parts[0] + parts[1..].map(&:capitalize).join
+    end
+  end
+end

data/lib/dotypos/paged_result.rb

@@ -0,0 +1,83 @@
+module Dotypos
+  # Wraps a paginated list response from the API.
+  #
+  # The underlying API envelope (after snake_case conversion):
+  #   current_page, per_page, total_items_on_page, total_items_count,
+  #   first_page, last_page, next_page (number), prev_page (number)
+  #
+  # Usage:
+  #   result = client.orders.list(page: 1, limit: 50)
+  #   result.data           # => [Resource, Resource, ...]
+  #   result.next_page?     # => true / false
+  #   result.next_page      # => PagedResult (fetches page 2)
+  #   result.prev_page?     # => true / false
+  #   result.prev_page      # => PagedResult (fetches page 1)
+  class PagedResult
+    attr_reader :data,
+                :current_page,
+                :per_page,
+                :total_items_on_page,
+                :total_items_count,
+                :first_page,
+                :last_page
+
+    def initialize(collection, envelope, request_params = {})
+      @collection     = collection
+      @request_params = request_params
+      assign_envelope(envelope)
+    end
+
+    # True when the API reports a next page exists.
+    # For high-volume entities (orders, order-items) where next_page may be null,
+    # we also check whether the current page is full.
+    def next_page?
+      if @next_page_number
+        true
+      elsif @per_page && @total_items_on_page
+        @total_items_on_page >= @per_page
+      else
+        false
+      end
+    end
+
+    # True when there is a previous page.
+    def prev_page?
+      @prev_page_number ? @prev_page_number >= 1 : (@current_page && @current_page > 1)
+    end
+
+    # Fetches and returns the next PagedResult, or nil if on the last page.
+    def next_page
+      return nil unless next_page?
+
+      page_number = @next_page_number || (@current_page + 1)
+      @collection.list(@request_params.merge(page: page_number))
+    end
+
+    # Fetches and returns the previous PagedResult, or nil if on the first page.
+    def prev_page
+      return nil unless prev_page?
+
+      page_number = @prev_page_number || (@current_page - 1)
+      @collection.list(@request_params.merge(page: page_number))
+    end
+
+    def inspect
+      "#<#{self.class.name} page=#{current_page} items=#{data.size} " \
+        "next=#{next_page?} prev=#{prev_page?}>"
+    end
+
+    private
+
+    def assign_envelope(envelope)
+      @data                = Array(envelope[:data]).map { |item| Resource.new(item) }
+      @current_page        = envelope[:current_page]
+      @per_page            = envelope[:per_page]
+      @total_items_on_page = envelope[:total_items_on_page]
+      @total_items_count   = envelope[:total_items_count]
+      @first_page          = envelope[:first_page]
+      @last_page           = envelope[:last_page]
+      @next_page_number    = envelope[:next_page]
+      @prev_page_number    = envelope[:prev_page]
+    end
+  end
+end

data/lib/dotypos/resource.rb

@@ -0,0 +1,63 @@
+module Dotypos
+  # Generic response object representing any API entity (order, product, customer, …).
+  #
+  # All keys are snake_case symbols. Attribute access is available via:
+  #   - Dot notation:   resource.total_price
+  #   - Hash notation:  resource[:total_price]
+  #   - Plain hash:     resource.to_h
+  #
+  # The ETag received from a GET response is stored on the object and is
+  # automatically used by ResourceCollection#update and #replace.
+  class Resource
+    attr_accessor :etag
+
+    def initialize(attributes, etag: nil)
+      @attributes = KeyTransformer.to_snake(attributes)
+      @etag       = etag
+    end
+
+    # Hash-style access with either symbol or string key.
+    def [](key)
+      @attributes[KeyTransformer.snake_key(key)]
+    end
+
+    # Returns a plain snake_case-keyed hash (deep copy).
+    def to_h
+      deep_dup(@attributes)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@attributes.inspect}>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def ==(other)
+      other.is_a?(Resource) && other.to_h == to_h
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @attributes.key?(name) || super
+    end
+
+    def method_missing(name, *args)
+      if @attributes.key?(name)
+        @attributes[name]
+      else
+        super
+      end
+    end
+
+    private
+
+    def deep_dup(obj)
+      case obj
+      when Hash  then obj.transform_values { |v| deep_dup(v) }
+      when Array then obj.map { |v| deep_dup(v) }
+      else obj
+      end
+    end
+  end
+end

data/lib/dotypos/resource_collection.rb

@@ -0,0 +1,144 @@
+module Dotypos
+  # Provides CRUD operations for a single API resource type.
+  #
+  # All methods are reached via the client accessors:
+  #   client.orders         # => ResourceCollection scoped to "order"
+  #   client.products       # => ResourceCollection scoped to "product"
+  #
+  # List
+  #   result = client.orders.list(page: 1, limit: 50, filter: "...", sort: "-created")
+  #   # => PagedResult
+  #
+  # Get single
+  #   order = client.orders.get("123456789")
+  #   # => Resource (with ETag set)
+  #
+  # Create
+  #   order = client.orders.create(note: "Table 4", table_id: "987")
+  #   # => Resource
+  #
+  # Update (PATCH — partial, requires ETag)
+  #   # Pass the Resource object — ETag is used automatically:
+  #   updated = client.orders.update(order, note: "Table 5")
+  #   # Or pass id + attrs + explicit etag:
+  #   updated = client.orders.update("123", { note: "Table 5" }, etag: "abc123")
+  #
+  # Replace (PUT — full replace, requires ETag)
+  #   replaced = client.orders.replace(order, full_attributes_hash)
+  #   replaced = client.orders.replace("123", full_attributes_hash, etag: "abc123")
+  #
+  # Delete
+  #   client.orders.delete("123456789")   # => true
+  class ResourceCollection
+    def initialize(client, path)
+      @client = client
+      @path   = path
+    end
+
+    # Returns a PagedResult.
+    #
+    # @param params [Hash] query parameters: page:, limit:, filter:, sort:
+    #   filter can be a String (raw API filter) or a FilterBuilder instance.
+    def list(params = {})
+      params = normalize_list_params(params)
+      response = @client.request(:get, collection_path, params: params)
+      envelope = KeyTransformer.to_snake(response.fetch(:body))
+      PagedResult.new(self, envelope, params)
+    end
+
+    # Returns a single Resource with its ETag populated.
+    def get(id)
+      response = @client.request(:get, member_path(id))
+      Resource.new(response.fetch(:body), etag: response[:etag])
+    end
+
+    # Creates one or more resources. Pass a Hash for a single resource or an
+    # Array of Hashes for batch creation.
+    # Returns a Resource (single) or Array<Resource> (batch).
+    def create(attributes)
+      body     = KeyTransformer.to_camel(attributes)
+      response = @client.request(:post, collection_path, body: body)
+
+      if response[:body].is_a?(Array)
+        response[:body].map { |item| Resource.new(item) }
+      else
+        Resource.new(response.fetch(:body), etag: response[:etag])
+      end
+    end
+
+    # Partial update (PATCH). Requires the current ETag.
+    #
+    # @overload update(resource, attributes = {})
+    #   @param resource   [Resource] existing resource (ETag extracted automatically)
+    #   @param attributes [Hash]     fields to update; merged with resource data when empty
+    #
+    # @overload update(id, attributes, etag: "...")
+    #   @param id         [String]  entity ID
+    #   @param attributes [Hash]    fields to update
+    #   @param options    [Hash]    accepts :etag — current ETag from a prior GET
+    def update(resource_or_id, attributes = {}, options = {})
+      id, attrs, tag = resolve_mutation_args(resource_or_id, attributes, options[:etag])
+      body     = KeyTransformer.to_camel(attrs.merge(id: id))
+      response = @client.request(:patch, member_path(id), body: body,
+                                                          headers: { "If-Match" => tag })
+      Resource.new(response.fetch(:body), etag: response[:etag])
+    end
+
+    # Full replace (PUT). Requires the current ETag.
+    #
+    # @overload replace(resource, attributes = {})
+    # @overload replace(id, attributes, etag: "...")
+    def replace(resource_or_id, attributes = {}, options = {})
+      id, attrs, tag = resolve_mutation_args(resource_or_id, attributes, options[:etag])
+      body     = KeyTransformer.to_camel(attrs.merge(id: id))
+      response = @client.request(:put, member_path(id), body: body,
+                                                        headers: { "If-Match" => tag })
+      Resource.new(response.fetch(:body), etag: response[:etag])
+    end
+
+    # Deletes the resource with the given id. Returns true on success.
+    def delete(id)
+      @client.request(:delete, member_path(id))
+      true
+    end
+
+    private
+
+    def collection_path
+      "clouds/#{@client.cloud_id}/#{@path}"
+    end
+
+    def member_path(id)
+      "clouds/#{@client.cloud_id}/#{@path}/#{id}"
+    end
+
+    def resolve_mutation_args(resource_or_id, attributes, explicit_etag)
+      id, attrs, tag = if resource_or_id.is_a?(Resource)
+                         args_from_resource(resource_or_id, attributes, explicit_etag)
+                       else
+                         [resource_or_id.to_s, attributes, explicit_etag]
+                       end
+
+      raise ArgumentError, etag_required_message if tag.nil?
+
+      [id, attrs, tag]
+    end
+
+    def args_from_resource(resource, attributes, explicit_etag)
+      id    = resource[:id].to_s
+      attrs = attributes.empty? ? resource.to_h : attributes
+      tag   = explicit_etag || resource.etag
+      [id, attrs, tag]
+    end
+
+    def etag_required_message
+      "An ETag is required for PUT/PATCH. Obtain one via #get first, " \
+        "then pass the Resource object or supply etag: explicitly."
+    end
+
+    def normalize_list_params(params)
+      params = params.merge(filter: params[:filter].to_s) if params[:filter].is_a?(FilterBuilder)
+      params.compact
+    end
+  end
+end

data/lib/dotypos/token_manager.rb

@@ -0,0 +1,98 @@
+require "faraday"
+require "json"
+
+module Dotypos
+  # Manages obtaining and refreshing the short-lived access token.
+  #
+  # The Dotypos auth flow (Step 2 of the documented OAuth model):
+  #   POST /v2/signin/token
+  #   Authorization: User {refreshToken}
+  #   Body: { "_cloudId": "123" }
+  #   Response: { "accessToken": "eyJ0..." }
+  #
+  # Access tokens expire in ~1 hour. This class keeps the token in memory,
+  # checks expiry before each use, and refreshes proactively (60 s buffer).
+  # A Mutex ensures thread safety.
+  class TokenManager
+    TOKEN_EXPIRY_SECONDS = 3600
+    EXPIRY_BUFFER_SECONDS = 60
+    AUTH_ENDPOINT = "signin/token".freeze
+
+    def initialize(refresh_token:, cloud_id:, base_url:, open_timeout: 5, timeout: 30)
+      @refresh_token = refresh_token
+      @cloud_id      = cloud_id.to_s
+      @base_url      = base_url
+      @open_timeout  = open_timeout
+      @timeout       = timeout
+      @access_token  = nil
+      @expires_at    = nil
+      @mutex         = Mutex.new
+    end
+
+    # Returns a valid access token, refreshing if necessary.
+    def access_token
+      @mutex.synchronize do
+        refresh! if token_expired?
+        @access_token
+      end
+    end
+
+    # Forces a token refresh regardless of expiry. Used when the server
+    # returns 401 mid-session (e.g. token invalidated server-side).
+    # Returns the new access token.
+    def force_refresh!
+      @mutex.synchronize do
+        refresh!
+        @access_token
+      end
+    end
+
+    private
+
+    def token_expired?
+      @access_token.nil? ||
+        @expires_at.nil? ||
+        Time.now >= @expires_at - EXPIRY_BUFFER_SECONDS
+    end
+
+    def refresh!
+      response = post_token_request
+      validate_token_response!(response)
+      store_access_token(response.body)
+    end
+
+    def post_token_request
+      auth_connection.post(AUTH_ENDPOINT) do |req|
+        req.headers["Authorization"] = "User #{@refresh_token}"
+        req.headers["Content-Type"]  = "application/json"
+        req.body = JSON.generate("_cloudId" => @cloud_id)
+      end
+    end
+
+    def validate_token_response!(response)
+      return if response.status == 200
+
+      raise Dotypos::AuthenticationError.new(
+        "Failed to obtain access token",
+        http_status: response.status,
+        http_body: response.body
+      )
+    end
+
+    def store_access_token(body)
+      parsed = JSON.parse(body)
+      @access_token = parsed["accessToken"] || parsed["access_token"]
+      raise Dotypos::AuthenticationError, "No accessToken in auth response: #{body}" if @access_token.nil?
+
+      @expires_at = Time.now + TOKEN_EXPIRY_SECONDS
+    end
+
+    def auth_connection
+      @auth_connection ||= Faraday.new(url: @base_url) do |f|
+        f.options.open_timeout = @open_timeout
+        f.options.timeout      = @timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/dotypos/version.rb

@@ -0,0 +1,3 @@
+module Dotypos
+  VERSION = "0.1.0".freeze
+end

data/lib/dotypos.rb

@@ -0,0 +1,26 @@
+require_relative "dotypos/version"
+require_relative "dotypos/errors"
+require_relative "dotypos/configuration"
+require_relative "dotypos/key_transformer"
+require_relative "dotypos/token_manager"
+require_relative "dotypos/resource"
+require_relative "dotypos/paged_result"
+require_relative "dotypos/filter_builder"
+require_relative "dotypos/resource_collection"
+require_relative "dotypos/client"
+
+module Dotypos
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: dotypos
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stockbird Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.68'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.68'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: A Ruby gem for interacting with the Dotypos API v2. Handles authentication,
+  token refresh, pagination, and provides a clean interface to all API resources.
+email:
+- info@stockbird.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/dotypos.rb
+- lib/dotypos/client.rb
+- lib/dotypos/configuration.rb
+- lib/dotypos/errors.rb
+- lib/dotypos/filter_builder.rb
+- lib/dotypos/key_transformer.rb
+- lib/dotypos/paged_result.rb
+- lib/dotypos/resource.rb
+- lib/dotypos/resource_collection.rb
+- lib/dotypos/token_manager.rb
+- lib/dotypos/version.rb
+homepage: https://github.com/stockbird-app/dotypos
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/stockbird-app/dotypos/issues
+  changelog_uri: https://github.com/stockbird-app/dotypos/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/stockbird-app/dotypos
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Ruby API client for Dotypos (Dotykačka)
+test_files: []