choiceqr 0.1.0

data/lib/choiceqr/resource.rb

@@ -0,0 +1,84 @@
+module ChoiceQR
+  # Generic response object representing any API entity (dish, order, area, …).
+  #
+  # 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
+  #
+  # Unlike the top level, ChoiceQR schemas are deeply nested (a dish carries
+  # menu options, which carry option list items; an order carries items,
+  # which carry modifiers, etc.) and the API has no `include`-style flag to
+  # opt in or out of them. So every nested Hash — at any depth — is wrapped
+  # as a Resource too, and every nested Array of Hashes becomes an Array of
+  # Resource, giving dot access all the way down.
+  class Resource
+    # +attributes+ is nil for a 200/201 response with an empty body, which
+    # the API returns for a handful of endpoints.
+    def initialize(attributes)
+      # Only this level's keys need converting: #wrap recurses into
+      # Resource.new for every nested Hash, which converts its own keys in
+      # turn. Pre-converting the whole tree here (e.g. via
+      # KeyTransformer.to_snake) would redo that work once per ancestor for
+      # every nested node.
+      @attributes = (attributes || {}).transform_keys { |k| KeyTransformer.snake_key(k) }
+                                      .transform_values { |v| self.class.wrap(v) }
+    end
+
+    # Wraps a single value: Hash → Resource, Array → Array of wrapped values,
+    # anything else is returned unchanged.
+    def self.wrap(value)
+      case value
+      when Hash  then new(value)
+      when Array then value.map { |v| wrap(v) }
+      else value
+      end
+    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, nested Resources
+    # unwrapped back to Hash).
+    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 Resource then obj.to_h
+      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/choiceqr/resources/areas.rb

@@ -0,0 +1,37 @@
+module ChoiceQR
+  module Resources
+    # Ordering areas (bar, hall, terrace, takeaway, delivery, digital menu).
+    #
+    #   client.areas.list
+    #   client.areas.get_by_type("takeaway")
+    #   client.areas.create(name: "Terrace", payment_methods: { cash: true, card: true })
+    #   client.areas.delete(id)
+    class Areas < Base
+      def list(language: nil)
+        fetch_list("location/#{lang(language)}/areas/list")
+      end
+
+      def get(id, language: nil)
+        fetch_one("location/#{lang(language)}/areas/#{id}")
+      end
+
+      # +type+ is one of: takeaway, delivery, simple, digitalMenu
+      def get_by_type(type, language: nil)
+        fetch_one("location/#{lang(language)}/areas/by-type/#{type}")
+      end
+
+      def create(language: nil, **attributes)
+        post_create("location/#{lang(language)}/areas", attributes)
+      end
+
+      # PUT — full replace. Returns true on success.
+      def update(id, language: nil, **attributes)
+        mutate(:put, "location/#{lang(language)}/areas/#{id}", body: attributes)
+      end
+
+      def delete(id, language: nil)
+        destroy("location/#{lang(language)}/areas/#{id}")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/base.rb

@@ -0,0 +1,69 @@
+module ChoiceQR
+  module Resources
+    # Shared plumbing for the per-entity resource wrapper classes reached via
+    # the client accessors (client.sections, client.dishes, client.orders, …).
+    #
+    # ChoiceQR's endpoints are not path-uniform the way Dotypos's are (list
+    # scoping, nesting, and available actions differ per resource type), so
+    # unlike a single generic ResourceCollection, each entity gets its own
+    # small class here that knows its own paths.
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+
+      # Resolves the :language path segment: an explicit override, or the
+      # client's configured default_language.
+      def lang(language)
+        (language || client.default_language).to_s
+      end
+
+      def fetch_one(path, params: {})
+        response = client.request(:get, path, params: to_query(params))
+        Resource.new(response.fetch(:body))
+      end
+
+      def fetch_list(path, params: {})
+        response = client.request(:get, path, params: to_query(params))
+        Array(response.fetch(:body)).map { |item| Resource.new(item) }
+      end
+
+      def post_create(path, attributes, params: {})
+        response = client.request(:post, path, body: KeyTransformer.to_camel(attributes), params: to_query(params))
+        Resource.new(response.fetch(:body))
+      end
+
+      # PUT/PATCH/POST calls that return 204 No Content on success.
+      def mutate(method, path, body: nil, params: {})
+        client.request(method, path, body: body && KeyTransformer.to_camel(body), params: to_query(params))
+        true
+      end
+
+      def destroy(path)
+        client.request(:delete, path)
+        true
+      end
+
+      # Query params use camelCase names too (e.g. includeApproved, perPage),
+      # same as request bodies.
+      def to_query(params)
+        KeyTransformer.to_camel(params.compact)
+      end
+
+      def format_time(value)
+        return nil if value.nil?
+        return value.to_s unless value.respond_to?(:iso8601)
+
+        # Time/DateTime#iso8601 take an optional fractional-digits argument;
+        # Date#iso8601 (no time component) takes none. Check arity instead of
+        # is_a?(Date) so any iso8601-compatible object works, not just those
+        # two stdlib classes.
+        value.method(:iso8601).arity.zero? ? value.iso8601 : value.iso8601(3)
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/bookings.rb

@@ -0,0 +1,32 @@
+module ChoiceQR
+  module Resources
+    # Table bookings/reservations.
+    #
+    #   client.bookings.list(from: Time.now, till: Time.now + 86_400 * 7)
+    #   client.bookings.get(id)
+    #   client.bookings.confirm(id, location_points: [point_id])
+    #   client.bookings.cancel(id, cancel_reason: "Table no longer available")
+    class Bookings < Base
+      # Rate limit: 1 request / 5 seconds.
+      def list(from: nil, till: nil, period_field: nil, page: nil, per_page: nil)
+        fetch_list("bookings/list", params: {
+                     from: format_time(from), till: format_time(till),
+                     period_field: period_field, page: page, per_page: per_page
+                   })
+      end
+
+      def get(id)
+        fetch_one("bookings/#{id}")
+      end
+
+      # Only allowed while the booking status is created.
+      def confirm(id, location_points: nil)
+        mutate(:put, "bookings/#{id}/confirm", body: { location_points: location_points }.compact)
+      end
+
+      def cancel(id, cancel_reason:)
+        mutate(:put, "bookings/#{id}/cancel", body: { cancel_reason: cancel_reason })
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/categories.rb

@@ -0,0 +1,39 @@
+module ChoiceQR
+  module Resources
+    # Groupings of dishes within a section.
+    #
+    #   client.categories.list(section_id)
+    #   client.categories.create(name: "Hot", section: section_id)
+    #   client.categories.update(id, name: "Cold")
+    #   client.categories.set_position(section_id, [id1, id2])
+    #   client.categories.delete(id)
+    class Categories < Base
+      def list(section_id, language: nil)
+        fetch_list("menu/#{lang(language)}/categories/list/#{section_id}")
+      end
+
+      def get(id, language: nil)
+        fetch_one("menu/#{lang(language)}/categories/#{id}")
+      end
+
+      def create(language: nil, **attributes)
+        post_create("menu/#{lang(language)}/categories", attributes)
+      end
+
+      # PUT — full replace. Returns true on success.
+      def update(id, language: nil, **attributes)
+        mutate(:put, "menu/#{lang(language)}/categories/#{id}", body: attributes)
+      end
+
+      # Reorders categories within +section_id+. +ids+ is the full, ordered
+      # array of category IDs.
+      def set_position(section_id, ids, language: nil)
+        mutate(:post, "menu/#{lang(language)}/categories/#{section_id}/position/bulk", body: ids)
+      end
+
+      def delete(id, language: nil)
+        destroy("menu/#{lang(language)}/categories/#{id}")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/cutlery.rb

@@ -0,0 +1,18 @@
+module ChoiceQR
+  module Resources
+    # Cutlery modal configuration (single settings object, no id).
+    #
+    #   client.cutlery.get
+    #   client.cutlery.update(show: true, required_cutlery: false)
+    class Cutlery < Base
+      def get(language: nil)
+        fetch_one("menu/#{lang(language)}/cutlery")
+      end
+
+      # PUT — returns true on success.
+      def update(language: nil, **attributes)
+        mutate(:put, "menu/#{lang(language)}/cutlery", body: attributes)
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/dish_labels.rb

@@ -0,0 +1,12 @@
+module ChoiceQR
+  module Resources
+    # Personal (custom) dish labels, e.g. "Chef's pick".
+    #
+    #   client.dish_labels.list   # => Array<Resource>
+    class DishLabels < Base
+      def list(language: nil)
+        fetch_list("menu/#{lang(language)}/dish-labels/list")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/dish_options.rb

@@ -0,0 +1,48 @@
+module ChoiceQR
+  module Resources
+    # Customizable dish options (single/multiple choice modifiers), shared
+    # across the dishes they are attached to.
+    #
+    #   client.dish_options.list(section_id)
+    #   client.dish_options.create(name: "Size", type: "single", section: section_id)
+    #   client.dish_options.attach(option_id, dish_id)
+    #   client.dish_options.detach(option_id, dish_id)
+    #   client.dish_options.delete(id)
+    class DishOptions < Base
+      def list(section_id, language: nil)
+        fetch_list("menu/#{lang(language)}/options/list/#{section_id}")
+      end
+
+      def get(id, language: nil)
+        fetch_one("menu/#{lang(language)}/options/#{id}")
+      end
+
+      def create(language: nil, **attributes)
+        post_create("menu/#{lang(language)}/options", attributes)
+      end
+
+      # PUT — full replace. Returns true on success.
+      def update(id, language: nil, **attributes)
+        mutate(:put, "menu/#{lang(language)}/options/#{id}", body: attributes)
+      end
+
+      # Reorders options within +section_id+. +ids+ is the full, ordered
+      # array of option IDs.
+      def set_position(section_id, ids, language: nil)
+        mutate(:post, "menu/#{lang(language)}/options/#{section_id}/position/bulk", body: ids)
+      end
+
+      def delete(id, language: nil)
+        destroy("menu/#{lang(language)}/options/#{id}")
+      end
+
+      def attach(id, dish_id, language: nil)
+        mutate(:put, "menu/#{lang(language)}/options/#{id}/attach", body: { dish: dish_id })
+      end
+
+      def detach(id, dish_id, language: nil)
+        mutate(:put, "menu/#{lang(language)}/options/#{id}/detach", body: { dish: dish_id })
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/dishes.rb

@@ -0,0 +1,58 @@
+module ChoiceQR
+  module Resources
+    # Menu items.
+    #
+    #   client.dishes.list(category_id)
+    #   client.dishes.find_by_pos_id("b9e8db61")
+    #   client.dishes.create(name: "Cappuccino", category: category_id, price: 420)
+    #   client.dishes.update(id, name: "Double Espresso", price: 450)
+    #   client.dishes.patch(id, active: false)
+    #   client.dishes.update_areas(id, takeaway: true, delivery: false)
+    #   client.dishes.set_position(category_id, [id1, id2])
+    #   client.dishes.delete(id)
+    class Dishes < Base
+      def list(category_id, language: nil)
+        fetch_list("menu/#{lang(language)}/dishes/list/#{category_id}")
+      end
+
+      # Looks a dish up by the posID assigned in your own POS system.
+      def find_by_pos_id(pos_id, language: nil)
+        fetch_one("menu/#{lang(language)}/dishes", params: { pos_id: pos_id })
+      end
+
+      def get(id, language: nil)
+        fetch_one("menu/#{lang(language)}/dishes/#{id}")
+      end
+
+      def create(language: nil, **attributes)
+        post_create("menu/#{lang(language)}/dishes", attributes)
+      end
+
+      # PUT — full replace. Returns true on success.
+      def update(id, language: nil, **attributes)
+        mutate(:put, "menu/#{lang(language)}/dishes/#{id}", body: attributes)
+      end
+
+      # PATCH — partial update of only the given fields.
+      def patch(id, language: nil, **attributes)
+        mutate(:patch, "menu/#{lang(language)}/dishes/#{id}", body: attributes)
+      end
+
+      # Updates which areas (takeaway/delivery/dine-in/digital menu) the dish
+      # is available in.
+      def update_areas(id, language: nil, **areas)
+        mutate(:put, "menu/#{lang(language)}/dishes/#{id}/areas", body: areas)
+      end
+
+      # Reorders dishes within +category_id+. +ids+ is the full, ordered
+      # array of dish IDs.
+      def set_position(category_id, ids, language: nil)
+        mutate(:post, "menu/#{lang(language)}/dishes/#{category_id}/position/bulk", body: ids)
+      end
+
+      def delete(id, language: nil)
+        destroy("menu/#{lang(language)}/dishes/#{id}")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/feedbacks.rb

@@ -0,0 +1,30 @@
+module ChoiceQR
+  module Resources
+    # Customer feedback for orders and the restaurant in general.
+    #
+    #   client.feedbacks.list(type: "ORDER")
+    #   client.feedbacks.get(id)
+    #   client.feedbacks.create(
+    #     ref_id: order_id,
+    #     feedback: { type: "ORDER", rate_serve: 5, rate_dish: 4, language: "en" },
+    #     customer: { name: "John Doe", phone: "+380501234567" }
+    #   )
+    class Feedbacks < Base
+      def list(from: nil, to: nil, limit: nil, offset: nil, type: nil, sort: nil)
+        fetch_list("feedbacks", params: {
+                     from: format_time(from), to: format_time(to),
+                     limit: limit, offset: offset, type: type, sort: sort
+                   })
+      end
+
+      def get(id)
+        fetch_one("feedbacks/#{id}")
+      end
+
+      # Rate limit: 1 request / 10 seconds.
+      def create(**attributes)
+        post_create("feedbacks", attributes)
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/full_menu.rb

@@ -0,0 +1,56 @@
+module ChoiceQR
+  module Resources
+    # Whole-menu operations: fetching the full client menu in one call,
+    # bulk import/replace, availability sync, and marketplace data sync.
+    #
+    #   client.full_menu.list
+    #   client.full_menu.import(sections: [...], categories: [...], dishes: [...])
+    #   client.full_menu.patch_dishes(dishes: [...])
+    #   client.full_menu.sync_availability(dishes: [{ pos_id: "525", active: false }])
+    #   client.full_menu.sync_chain_availability(sections: [...])
+    #   client.full_menu.sync_marketplace_data(dishes: [{ pos_id: "1", data: { WOLT: { price: 1000 } } }])
+    #   client.full_menu.marketplace_sync_status(sync_id)
+    class FullMenu < Base
+      def list(language: nil)
+        fetch_one("menu/#{lang(language)}/full/list")
+      end
+
+      # Full replace of the menu (sections:, categories:, dishes:, dish_options:).
+      # By default, entities missing from the payload are deleted; pass
+      # preserve_missing_items: true to keep them (marked inactive) instead.
+      def import(language: nil, preserve_missing_items: nil, **payload)
+        mutate(:post, "menu/#{lang(language)}/full", body: payload,
+                                                     params: { preserve_missing_items: preserve_missing_items })
+      end
+
+      # Partial update of only dish data (dishes:), matched by posID.
+      def patch_dishes(language: nil, **payload)
+        mutate(:patch, "menu/#{lang(language)}/full/dishes", body: payload)
+      end
+
+      # Bulk-updates active/attribute state for sections:, categories:,
+      # dishes:, and dish_options:, matched by posID. At least one of these
+      # keys must be present.
+      def sync_availability(language: nil, skip_missing: nil, **payload)
+        mutate(:post, "menu/#{lang(language)}/full/availability", body: payload,
+                                                                  params: { skip_missing: skip_missing })
+      end
+
+      # Same as #sync_availability, but per chain branch.
+      def sync_chain_availability(language: nil, **payload)
+        mutate(:post, "menu/#{lang(language)}/full/chain/availability", body: payload)
+      end
+
+      # Kicks off an async sync of marketplace-specific price/name overrides.
+      # Returns a Resource with the sync job +id+; poll it via
+      # #marketplace_sync_status.
+      def sync_marketplace_data(dishes:, language: nil)
+        post_create("menu/#{lang(language)}/full/marketplace/data", { dishes: dishes })
+      end
+
+      def marketplace_sync_status(sync_id, language: nil)
+        fetch_one("menu/#{lang(language)}/full/marketplace/data/status/#{sync_id}")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/location_points.rb

@@ -0,0 +1,31 @@
+module ChoiceQR
+  module Resources
+    # Individual points within an area (tables, kiosks, rooms).
+    #
+    #   client.location_points.list(area_id)
+    #   client.location_points.create(name: "Table 4", area: area_id)
+    #   client.location_points.delete(id)
+    class LocationPoints < Base
+      def list(area_id, language: nil)
+        fetch_list("location/#{lang(language)}/points/list/#{area_id}")
+      end
+
+      def get(id, language: nil)
+        fetch_one("location/#{lang(language)}/points/#{id}")
+      end
+
+      def create(language: nil, **attributes)
+        post_create("location/#{lang(language)}/points", attributes)
+      end
+
+      # PUT — full replace. Returns true on success.
+      def update(id, language: nil, **attributes)
+        mutate(:put, "location/#{lang(language)}/points/#{id}", body: attributes)
+      end
+
+      def delete(id, language: nil)
+        destroy("location/#{lang(language)}/points/#{id}")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/orders.rb

@@ -0,0 +1,59 @@
+module ChoiceQR
+  module Resources
+    # Customer orders (delivery, takeaway, or table).
+    #
+    #   client.orders.list(since: Time.now - 3600)
+    #   client.orders.list_archive(from: Time.now - 86_400 * 30, till: Time.now)
+    #   client.orders.get(id)
+    #   client.orders.get_by_guid(guid)
+    #   client.orders.update_delivery(id, delivery_status: "processing")
+    #   client.orders.cancel(id, reason: "Out of stock")
+    #   client.orders.close(id)
+    class Orders < Base
+      def list(since: nil, include_approved: nil, branches: nil, page: nil, per_page: nil)
+        fetch_list("orders/list", params: {
+                     since: format_time(since), include_approved: include_approved,
+                     branches: format_branches(branches), page: page, per_page: per_page
+                   })
+      end
+
+      # Rate limit: 1 request / 5 seconds.
+      def list_archive(from:, till:, branches: nil, page: nil, per_page: nil)
+        fetch_list("orders/list/archive", params: {
+                     from: format_time(from), till: format_time(till),
+                     branches: format_branches(branches), page: page, per_page: per_page
+                   })
+      end
+
+      def get(id)
+        fetch_one("orders/#{id}")
+      end
+
+      def get_by_guid(guid)
+        fetch_one("orders/guid/#{guid}")
+      end
+
+      # Only allowed while the order status is approved or delivery.
+      def update_delivery(id, **attributes)
+        mutate(:put, "orders/#{id}/delivery", body: attributes)
+      end
+
+      # Only allowed while the order status is waiting_for_approve, approved,
+      # or delivery.
+      def cancel(id, reason:)
+        mutate(:put, "orders/#{id}/cancel", body: { reason: reason })
+      end
+
+      # Only allowed while the order status is approved or delivery.
+      def close(id)
+        mutate(:put, "orders/#{id}/close")
+      end
+
+      private
+
+      def format_branches(branches)
+        Array(branches).join(",") if branches
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/pack.rb

@@ -0,0 +1,36 @@
+module ChoiceQR
+  module Resources
+    # Menu packages (bundles of categories sold together).
+    #
+    #   client.pack.list
+    #   client.pack.create(name: "Lunch set", price: 1000, categories: [{ _id: category_id }])
+    #   client.pack.delete(id)
+    #
+    # Note: entries in the +categories+ payload reference an existing
+    # category by its Mongo id. Use the literal key +:_id+ (or the string
+    # +"_id"+) — the leading underscore is preserved by the key transformer,
+    # unlike the top-level +id+ read from responses.
+    class Pack < Base
+      def list(language: nil)
+        fetch_list("menu/#{lang(language)}/pack/list")
+      end
+
+      def get(id, language: nil)
+        fetch_one("menu/#{lang(language)}/pack/#{id}")
+      end
+
+      def create(language: nil, **attributes)
+        post_create("menu/#{lang(language)}/pack", attributes)
+      end
+
+      # PUT — full replace. Returns true on success.
+      def update(id, language: nil, **attributes)
+        mutate(:put, "menu/#{lang(language)}/pack/#{id}", body: attributes)
+      end
+
+      def delete(id, language: nil)
+        destroy("menu/#{lang(language)}/pack/#{id}")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/place.rb

@@ -0,0 +1,13 @@
+module ChoiceQR
+  module Resources
+    # Information about the place (restaurant, cafe) the client's token
+    # belongs to.
+    #
+    #   client.place.get   # => Resource
+    class Place < Base
+      def get
+        fetch_one("place")
+      end
+    end
+  end
+end

data/lib/choiceqr/resources/section_info.rb

@@ -0,0 +1,12 @@
+module ChoiceQR
+  module Resources
+    # The customizable message shown at the top of a menu section.
+    #
+    #   client.section_info.get(section_id)   # => Resource
+    class SectionInfo < Base
+      def get(section_id, language: nil)
+        fetch_one("menu/#{lang(language)}/section-info/#{section_id}")
+      end
+    end
+  end
+end