loyverse_api 0.1.0

data/lib/loyverse_api/endpoints/discounts.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module LoyverseApi
+  module Endpoints
+    module Discounts
+      # Discount type constants
+      TYPE_FIXED_PERCENT = "FIXED_PERCENT"
+      TYPE_FIXED_AMOUNT = "FIXED_AMOUNT"
+      TYPE_VARIABLE_PERCENT = "VARIABLE_PERCENT"
+      TYPE_VARIABLE_AMOUNT = "VARIABLE_AMOUNT"
+      TYPE_DISCOUNT_BY_POINTS = "DISCOUNT_BY_POINTS"
+
+      # Applies to constants
+      APPLIES_TO_RECEIPT = "RECEIPT"
+      APPLIES_TO_ITEM = "ITEM"
+
+      # Default applies_to value
+      DEFAULT_APPLIES_TO = APPLIES_TO_RECEIPT
+
+      # Get a specific discount by ID
+      # @param discount_id [String] UUID of the discount
+      # @return [Hash] Discount details
+      def get_discount(discount_id)
+        get("discounts/#{discount_id}")
+      end
+
+      # List discounts
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @param updated_at_min [String, Time] Filter by minimum update time (ISO 8601)
+      # @param updated_at_max [String, Time] Filter by maximum update time (ISO 8601)
+      # @return [Hash] Response with discounts array
+      def list_discounts(limit: 250, cursor: nil, updated_at_min: nil, updated_at_max: nil)
+        params = {
+          limit: limit,
+          cursor: cursor,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max)
+        }.compact
+
+        get("discounts", params: params)
+      end
+
+      # Create a new discount
+      # @param name [String] Discount name
+      # @param type [String] Type of discount: "FIXED_PERCENT", "FIXED_AMOUNT", "VARIABLE_PERCENT", "VARIABLE_AMOUNT", or "DISCOUNT_BY_POINTS"
+      # @param discount_amount [Float] Discount amount (percentage or fixed value, optional for variable types)
+      # @param applies_to [String] What the discount applies to: "RECEIPT" or "ITEM" (optional, default: "RECEIPT")
+      # @param enabled [Boolean] Whether the discount is enabled (optional)
+      # @return [Hash] Created discount details
+      def create_discount(name:, type:, discount_amount: nil, applies_to: DEFAULT_APPLIES_TO, enabled: true)
+        body = {
+          name: name,
+          type: type.upcase,
+          discount_amount: discount_amount,
+          applies_to: applies_to.upcase,
+          enabled: enabled
+        }.compact
+
+        post("discounts", body: body)
+      end
+
+      # Update an existing discount
+      # @param discount_id [String] UUID of the discount
+      # @param name [String] Discount name (optional)
+      # @param type [String] Type of discount: "FIXED_PERCENT", "FIXED_AMOUNT", "VARIABLE_PERCENT", "VARIABLE_AMOUNT", or "DISCOUNT_BY_POINTS" (optional)
+      # @param discount_amount [Float] Discount amount (optional)
+      # @param applies_to [String] What the discount applies to (optional)
+      # @param enabled [Boolean] Whether the discount is enabled (optional)
+      # @return [Hash] Updated discount details
+      def update_discount(discount_id, name: nil, type: nil, discount_amount: nil, applies_to: nil, enabled: nil)
+        body = {
+          name: name,
+          type: type&.upcase,
+          discount_amount: discount_amount,
+          applies_to: applies_to&.upcase,
+          enabled: enabled
+        }.compact
+
+        put("discounts/#{discount_id}", body: body)
+      end
+
+      # Delete a discount
+      # @param discount_id [String] UUID of the discount
+      # @return [Hash] Response
+      def delete_discount(discount_id)
+        delete("discounts/#{discount_id}")
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/employees.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LoyverseApi
+  module Endpoints
+    module Employees
+      # Get a specific employee by ID
+      # @param employee_id [String] UUID of the employee
+      # @return [Hash] Employee details
+      def get_employee(employee_id)
+        get("employees/#{employee_id}")
+      end
+
+      # List employees
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @param updated_at_min [String, Time] Filter by minimum update time (ISO 8601)
+      # @param updated_at_max [String, Time] Filter by maximum update time (ISO 8601)
+      # @return [Hash] Response with employees array
+      def list_employees(limit: 250, cursor: nil, updated_at_min: nil, updated_at_max: nil)
+        params = {
+          limit: limit,
+          cursor: cursor,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max)
+        }.compact
+
+        get("employees", params: params)
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/inventory.rb

@@ -0,0 +1,41 @@
+module LoyverseApi
+  module Endpoints
+    module Inventory
+      # List inventory levels
+      # @param variant_id [String] Filter by specific variant UUID (optional)
+      # @param store_id [String] Filter by specific store UUID (optional)
+      # @param updated_at_min [String, Time] Filter by minimum update time (optional)
+      # @param updated_at_max [String, Time] Filter by maximum update time (optional)
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @return [Hash] Response with inventory levels array
+      def list_inventory(variant_id: nil, store_id: nil, updated_at_min: nil, updated_at_max: nil, limit: 250, cursor: nil)
+        params = {
+          limit: limit,
+          variant_id: variant_id,
+          store_id: store_id,
+          cursor: cursor,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max)
+        }.compact
+
+        get("inventory", params: params)
+      end
+
+      # Update inventory level for a variant at a specific store
+      # @param variant_id [String] UUID of the variant
+      # @param store_id [String] UUID of the store
+      # @param in_stock [Integer] New stock quantity
+      # @return [Hash] Updated inventory level
+      def update_inventory(variant_id:, store_id:, in_stock:)
+        body = {
+          variant_id: variant_id,
+          store_id: store_id,
+          in_stock: in_stock
+        }
+
+        put("inventory", body: body)
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/items.rb

@@ -0,0 +1,75 @@
+module LoyverseApi
+  module Endpoints
+    module Items
+      # Get a specific item by ID
+      # @param item_id [String] UUID of the item
+      # @return [Hash] Item details
+      def get_item(item_id)
+        get("items/#{item_id}")
+      end
+
+      # List items
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @param updated_at_min [String, Time] Filter by minimum update time (ISO 8601)
+      # @param updated_at_max [String, Time] Filter by maximum update time (ISO 8601)
+      # @return [Hash] Response with items array
+      def list_items(limit: 250, cursor: nil, updated_at_min: nil, updated_at_max: nil)
+        params = {
+          limit: limit,
+          cursor: cursor,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max)
+        }.compact
+
+        get("items", params: params)
+      end
+
+      # Create a new item
+      # @param item_name [String] Name of the item
+      # @param category_id [String] UUID of the category (optional)
+      # @param variants [Array<Hash>] Array of variant hashes
+      # @param track_stock [Boolean] Whether to track inventory
+      # @param sold_by_weight [Boolean] Whether item is sold by weight
+      # @param is_composite [Boolean] Whether item is composite
+      # @return [Hash] Created item details
+      def create_item(item_name:, category_id: nil, variants: [], track_stock: false, sold_by_weight: false, is_composite: false)
+        body = {
+          item_name: item_name,
+          track_stock: track_stock,
+          sold_by_weight: sold_by_weight,
+          is_composite: is_composite
+        }
+        body[:category_id] = category_id if category_id
+        body[:variants] = variants unless variants.empty?
+
+        post("items", body: body)
+      end
+
+      # Update an existing item
+      # @param item_id [String] UUID of the item
+      # @param item_name [String] Name of the item (optional)
+      # @param category_id [String] UUID of the category (optional)
+      # @param variants [Array<Hash>] Array of variant hashes (optional)
+      # @param track_stock [Boolean] Whether to track inventory (optional)
+      # @return [Hash] Updated item details
+      def update_item(item_id, item_name: nil, category_id: nil, variants: nil, track_stock: nil)
+        body = {
+          item_name: item_name,
+          category_id: category_id,
+          variants: variants,
+          track_stock: track_stock
+        }.compact
+
+        put("items/#{item_id}", body: body)
+      end
+
+      # Delete an item
+      # @param item_id [String] UUID of the item
+      # @return [Hash] Response
+      def delete_item(item_id)
+        delete("items/#{item_id}")
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/modifiers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module LoyverseApi
+  module Endpoints
+    module Modifiers
+      # Get a specific modifier by ID
+      # @param modifier_id [String] UUID of the modifier
+      # @return [Hash] Modifier details
+      def get_modifier(modifier_id)
+        get("modifiers/#{modifier_id}")
+      end
+
+      # List modifiers
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @param updated_at_min [String, Time] Filter by minimum update time (ISO 8601)
+      # @param updated_at_max [String, Time] Filter by maximum update time (ISO 8601)
+      # @return [Hash] Response with modifiers array
+      def list_modifiers(limit: 250, cursor: nil, updated_at_min: nil, updated_at_max: nil)
+        params = {
+          limit: limit,
+          cursor: cursor,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max)
+        }.compact
+
+        get("modifiers", params: params)
+      end
+
+      # Create a new modifier
+      # @param name [String] Modifier name
+      # @param options [Array<Hash>] Array of modifier options with name and price
+      # @return [Hash] Created modifier details
+      def create_modifier(name:, options:)
+        body = {
+          name: name,
+          options: options
+        }
+
+        post("modifiers", body: body)
+      end
+
+      # Delete a modifier
+      # @param modifier_id [String] UUID of the modifier
+      # @return [Hash] Response
+      def delete_modifier(modifier_id)
+        delete("modifiers/#{modifier_id}")
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/receipts.rb

@@ -0,0 +1,115 @@
+module LoyverseApi
+  module Endpoints
+    module Receipts
+      # Get a specific receipt by receipt number
+      # @param receipt_number [String, Integer] Receipt number (not UUID)
+      # @return [Hash] Receipt details
+      def get_receipt(receipt_number)
+        get("receipts/#{receipt_number}")
+      end
+
+      # List receipts
+      # @param receipt_numbers [Array<String, Integer>] Array of specific receipt numbers (optional)
+      # @param since_receipt_number [String, Integer] Return receipts after this number (optional)
+      # @param before_receipt_number [String, Integer] Return receipts before this number (optional)
+      # @param store_id [String] Filter by store UUID (optional)
+      # @param order [String] Sort order: "ASC" or "DESC" (default: "DESC")
+      # @param source [String] Filter by source (e.g., "POS", "API") (optional)
+      # @param updated_at_min [String, Time] Filter by minimum update time (optional)
+      # @param updated_at_max [String, Time] Filter by maximum update time (optional)
+      # @param created_at_min [String, Time] Filter by minimum creation time (optional)
+      # @param created_at_max [String, Time] Filter by maximum creation time (optional)
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @return [Hash] Response with receipts array
+      def list_receipts(
+        receipt_numbers: nil,
+        since_receipt_number: nil,
+        before_receipt_number: nil,
+        store_id: nil,
+        order: "DESC",
+        source: nil,
+        updated_at_min: nil,
+        updated_at_max: nil,
+        created_at_min: nil,
+        created_at_max: nil,
+        limit: 250,
+        cursor: nil
+      )
+        params = {
+          limit: limit,
+          order: order,
+          receipt_numbers: receipt_numbers ? Array(receipt_numbers).join(",") : nil,
+          since_receipt_number: since_receipt_number,
+          before_receipt_number: before_receipt_number,
+          store_id: store_id,
+          source: source,
+          cursor: cursor,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max),
+          created_at_min: format_time(created_at_min),
+          created_at_max: format_time(created_at_max)
+        }.compact
+
+        get("receipts", params: params)
+      end
+
+      # Create a new receipt
+      # @param receipt_date [String, Time] Receipt date in ISO 8601 format
+      # @param store_id [String] UUID of the store
+      # @param line_items [Array<Hash>] Array of line item hashes
+      # @param payments [Array<Hash>] Array of payment hashes
+      # @param receipt_type [String] Type of receipt (default: "SALE")
+      # @param employee_id [String] UUID of the employee (optional)
+      # @param customer_id [String] UUID of the customer (optional)
+      # @param note [String] Receipt note (optional)
+      # @param source [String] Source of receipt (default: "API")
+      # @return [Hash] Created receipt details
+      def create_receipt(
+        receipt_date:,
+        store_id:,
+        line_items:,
+        payments:,
+        receipt_type: "SALE",
+        employee_id: nil,
+        customer_id: nil,
+        note: nil,
+        source: "API"
+      )
+        body = {
+          receipt_date: format_time(receipt_date),
+          receipt_type: receipt_type,
+          store_id: store_id,
+          line_items: line_items,
+          payments: payments,
+          source: source
+        }
+        body[:employee_id] = employee_id if employee_id
+        body[:customer_id] = customer_id if customer_id
+        body[:note] = note if note
+
+        post("receipts", body: body)
+      end
+
+      # Create a refund for a receipt
+      # @param receipt_number [String, Integer] Receipt number to refund
+      # @param refund_date [String, Time] Refund date in ISO 8601 format
+      # @param line_items [Array<Hash>] Array of line items to refund
+      # @param payments [Array<Hash>] Array of refund payments
+      # @param employee_id [String] UUID of the employee (optional)
+      # @param note [String] Refund note (optional)
+      # @return [Hash] Created refund receipt details
+      def create_refund(receipt_number, refund_date:, line_items:, payments:, employee_id: nil, note: nil)
+        body = {
+          refund_date: format_time(refund_date),
+          line_items: line_items,
+          payments: payments
+        }
+        body[:employee_id] = employee_id if employee_id
+        body[:note] = note if note
+
+        post("receipts/#{receipt_number}/refund", body: body)
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/webhooks.rb

@@ -0,0 +1,85 @@
+module LoyverseApi
+  module Endpoints
+    module Webhooks
+      # Get a specific webhook by ID
+      # @param webhook_id [String] UUID of the webhook
+      # @return [Hash] Webhook details
+      def get_webhook(webhook_id)
+        get("webhooks/#{webhook_id}")
+      end
+
+      # List all webhooks
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @return [Hash] Response with webhooks array
+      def list_webhooks(limit: 250, cursor: nil)
+        params = {
+          limit: limit,
+          cursor: cursor
+        }.compact
+
+        get("webhooks", params: params)
+      end
+
+      # Create a new webhook
+      # @param url [String] Webhook endpoint URL
+      # @param event_types [Array<String>] Array of event types to subscribe to
+      # @param description [String] Webhook description (optional)
+      # @return [Hash] Created webhook details
+      #
+      # Available event types:
+      # - ORDER_CREATED
+      # - ITEM_UPDATED
+      # - INVENTORY_UPDATED
+      def create_webhook(url:, event_types:, description: nil)
+        body = {
+          url: url,
+          event_types: Array(event_types)
+        }
+        body[:description] = description if description
+
+        post("webhooks", body: body)
+      end
+
+      # Delete a webhook
+      # @param webhook_id [String] UUID of the webhook
+      # @return [Hash] Response
+      def delete_webhook(webhook_id)
+        delete("webhooks/#{webhook_id}")
+      end
+
+      # Verify webhook signature (for OAuth 2.0 created webhooks)
+      # @param payload [String] Raw request body
+      # @param signature [String] X-Loyverse-Signature header value
+      # @param secret [String] Your webhook secret
+      # @return [Boolean] True if signature is valid
+      def verify_webhook_signature(payload, signature, secret)
+        return false if payload.nil? || signature.nil? || secret.nil?
+
+        require "openssl"
+
+        computed_signature = OpenSSL::HMAC.hexdigest(
+          OpenSSL::Digest.new("sha256"),
+          secret,
+          payload
+        )
+
+        secure_compare(computed_signature, signature)
+      end
+
+      private
+
+      # Constant-time string comparison to prevent timing attacks
+      def secure_compare(a, b)
+        return false if a.nil? || b.nil? || a.bytesize != b.bytesize
+
+        l = a.unpack("C*")
+        r = 0
+        i = -1
+
+        b.each_byte { |byte| r |= byte ^ l[i += 1] }
+        r == 0
+      end
+    end
+  end
+end

data/lib/loyverse_api/errors.rb

@@ -0,0 +1,19 @@
+module LoyverseApi
+  class Error < StandardError
+    attr_reader :code, :details
+
+    def initialize(message = nil, code: nil, details: nil)
+      @code = code
+      @details = details
+      super(message)
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class AuthorizationError < Error; end
+  class NotFoundError < Error; end
+  class BadRequestError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+  class ApiError < Error; end
+end

data/lib/loyverse_api/version.rb

@@ -0,0 +1,3 @@
+module LoyverseApi
+  VERSION = "0.1.0"
+end

data/lib/loyverse_api.rb

@@ -0,0 +1,33 @@
+require "faraday"
+require "faraday/retry"
+require "json"
+require "time"
+
+require_relative "loyverse_api/version"
+require_relative "loyverse_api/configuration"
+require_relative "loyverse_api/errors"
+require_relative "loyverse_api/endpoints/items"
+require_relative "loyverse_api/endpoints/categories"
+require_relative "loyverse_api/endpoints/inventory"
+require_relative "loyverse_api/endpoints/receipts"
+require_relative "loyverse_api/endpoints/webhooks"
+require_relative "loyverse_api/endpoints/customers"
+require_relative "loyverse_api/endpoints/discounts"
+require_relative "loyverse_api/endpoints/employees"
+require_relative "loyverse_api/endpoints/modifiers"
+require_relative "loyverse_api/client"
+
+module LoyverseApi
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  def self.client
+    Client.new(configuration)
+  end
+end

data/loyverse_api.gemspec

@@ -0,0 +1,34 @@
+require_relative 'lib/loyverse_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "loyverse_api"
+  spec.version       = LoyverseApi::VERSION
+  spec.authors       = ["Loyverse API Wrapper"]
+  spec.email         = ["hola@alvarodelgado.dev"]
+
+  spec.summary       = %q{Ruby wrapper for the Loyverse API}
+  spec.description   = %q{A comprehensive Ruby gem for interacting with the Loyverse API, supporting authentication, webhooks, and all major resources including items, inventory, receipts, and categories.}
+  spec.homepage      = "https://github.com/yourusername/loyverse_api"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "vcr", "~> 6.0"
+end