loyverse_api 0.1.0

data/examples/basic_usage.rb

@@ -0,0 +1,115 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'loyverse_api'
+
+# This example demonstrates basic usage of the Loyverse API gem
+
+# Configure the gem with your access token
+LoyverseApi.configure do |config|
+  config.access_token = ENV['LOYVERSE_ACCESS_TOKEN'] || 'your_access_token_here'
+end
+
+# Create a client instance
+client = LoyverseApi.client
+
+puts "=== Loyverse API Examples ==="
+puts
+
+# Example 1: List Categories
+puts "1. Listing categories:"
+begin
+  categories = client.categories.list(limit: 5)
+  if categories.empty?
+    puts "  No categories found"
+  else
+    categories.each do |category|
+      puts "  - #{category['name']} (#{category['color']})"
+    end
+  end
+rescue LoyverseApi::Error => e
+  puts "  Error: #{e.message}"
+end
+puts
+
+# Example 2: List Items
+puts "2. Listing items:"
+begin
+  items = client.items.list(limit: 5)
+  if items.empty?
+    puts "  No items found"
+  else
+    items.each do |item|
+      puts "  - #{item['item_name']}"
+      if item['variants']
+        item['variants'].each do |variant|
+          puts "    * SKU: #{variant['sku']}, Price: $#{variant['price']}"
+        end
+      end
+    end
+  end
+rescue LoyverseApi::Error => e
+  puts "  Error: #{e.message}"
+end
+puts
+
+# Example 3: Get Inventory Levels
+puts "3. Checking inventory:"
+begin
+  inventory = client.inventory.list(limit: 5)
+  if inventory.empty?
+    puts "  No inventory data found"
+  else
+    inventory.each do |level|
+      puts "  - Variant: #{level['variant_id']}"
+      puts "    Store: #{level['store_id']}"
+      puts "    In Stock: #{level['in_stock']}"
+      puts "    Updated: #{level['updated_at']}"
+      puts
+    end
+  end
+rescue LoyverseApi::Error => e
+  puts "  Error: #{e.message}"
+end
+puts
+
+# Example 4: List Recent Receipts
+puts "4. Listing recent receipts:"
+begin
+  receipts = client.receipts.list(limit: 5, order: 'DESC')
+  if receipts.empty?
+    puts "  No receipts found"
+  else
+    receipts.each do |receipt|
+      puts "  - Receipt ##{receipt['receipt_number']}"
+      puts "    Date: #{receipt['receipt_date']}"
+      puts "    Total: $#{receipt['total_money']}"
+      puts "    Items: #{receipt['line_items']&.count || 0}"
+      puts
+    end
+  end
+rescue LoyverseApi::Error => e
+  puts "  Error: #{e.message}"
+end
+puts
+
+# Example 5: List Webhooks
+puts "5. Listing webhooks:"
+begin
+  webhooks = client.webhooks.list
+  if webhooks.empty?
+    puts "  No webhooks configured"
+  else
+    webhooks.each do |webhook|
+      puts "  - #{webhook['url']}"
+      puts "    Events: #{webhook['event_types']&.join(', ')}"
+      puts "    Description: #{webhook['description']}"
+      puts
+    end
+  end
+rescue LoyverseApi::Error => e
+  puts "  Error: #{e.message}"
+end
+puts
+
+puts "=== Examples Complete ==="

data/examples/create_item.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'loyverse_api'
+
+# This example demonstrates how to create a new item with variants
+
+LoyverseApi.configure do |config|
+  config.access_token = ENV['LOYVERSE_ACCESS_TOKEN'] || 'your_access_token_here'
+end
+
+client = LoyverseApi.client
+
+puts "Creating a new item with variants..."
+puts
+
+begin
+  # First, create a category for the item
+  category = client.categories.create(
+    name: 'Beverages',
+    color: 'BLUE'
+  )
+  puts "Created category: #{category['name']} (ID: #{category['id']})"
+  puts
+
+  # Create an item with multiple variants
+  item = client.items.create(
+    item_name: 'Premium Coffee',
+    category_id: category['id'],
+    track_stock: true,
+    variants: [
+      {
+        sku: 'COFFEE-S-001',
+        barcode: '1234567890123',
+        price: 3.50,
+        cost: 1.50,
+        option1_value: 'Small'
+      },
+      {
+        sku: 'COFFEE-M-001',
+        barcode: '1234567890124',
+        price: 4.50,
+        cost: 2.00,
+        option1_value: 'Medium'
+      },
+      {
+        sku: 'COFFEE-L-001',
+        barcode: '1234567890125',
+        price: 5.50,
+        cost: 2.50,
+        option1_value: 'Large'
+      }
+    ]
+  )
+
+  puts "Created item: #{item['item_name']}"
+  puts "Item ID: #{item['id']}"
+  puts "Category: #{item['category_id']}"
+  puts
+  puts "Variants:"
+  item['variants'].each do |variant|
+    puts "  - #{variant['option1_value']}: $#{variant['price']} (SKU: #{variant['sku']})"
+  end
+  puts
+  puts "Item created successfully!"
+
+rescue LoyverseApi::Error => e
+  puts "Error creating item: #{e.message}"
+  puts "Error code: #{e.code}" if e.code
+  puts "Error details: #{e.details}" if e.details
+end

data/examples/webhook_server.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'loyverse_api'
+require 'webrick'
+require 'json'
+
+# This example demonstrates a simple webhook receiver server
+
+# Configure the Loyverse API client
+LoyverseApi.configure do |config|
+  config.access_token = ENV['LOYVERSE_ACCESS_TOKEN'] || 'your_access_token_here'
+end
+
+client = LoyverseApi.client
+
+# Webhook secret (if using OAuth 2.0 created webhooks)
+WEBHOOK_SECRET = ENV['LOYVERSE_WEBHOOK_SECRET']
+
+# Simple webhook handler
+class WebhookHandler < WEBrick::HTTPServlet::AbstractServlet
+  def initialize(server, client)
+    super(server)
+    @client = client
+  end
+
+  def do_POST(request, response)
+    begin
+      # Get the raw body
+      body = request.body
+
+      # Verify signature if using OAuth 2.0
+      if WEBHOOK_SECRET
+        signature = request.header['x-loyverse-signature']&.first
+        is_valid = @client.webhooks.verify_signature(body, signature, WEBHOOK_SECRET)
+
+        unless is_valid
+          response.status = 401
+          response.body = JSON.generate({ error: 'Invalid signature' })
+          return
+        end
+      end
+
+      # Parse the webhook payload
+      payload = JSON.parse(body)
+
+      # Handle the webhook event
+      handle_event(payload)
+
+      # Respond with 200 OK
+      response.status = 200
+      response['Content-Type'] = 'application/json'
+      response.body = JSON.generate({ received: true })
+
+    rescue JSON::ParserError => e
+      response.status = 400
+      response.body = JSON.generate({ error: 'Invalid JSON' })
+    rescue => e
+      puts "Error processing webhook: #{e.message}"
+      response.status = 500
+      response.body = JSON.generate({ error: 'Internal server error' })
+    end
+  end
+
+  private
+
+  def handle_event(payload)
+    event_type = payload['event_type']
+    data = payload['data']
+    timestamp = payload['timestamp']
+
+    puts "\n=== Webhook Received ==="
+    puts "Event Type: #{event_type}"
+    puts "Timestamp: #{timestamp}"
+    puts "Data: #{JSON.pretty_generate(data)}"
+    puts "========================\n"
+
+    case event_type
+    when 'ORDER_CREATED'
+      handle_order_created(data)
+    when 'ITEM_UPDATED'
+      handle_item_updated(data)
+    when 'INVENTORY_UPDATED'
+      handle_inventory_updated(data)
+    else
+      puts "Unknown event type: #{event_type}"
+    end
+  end
+
+  def handle_order_created(data)
+    puts "New order created: Receipt ##{data['receipt_number']}"
+    # Add your custom logic here
+  end
+
+  def handle_item_updated(data)
+    puts "Item updated: #{data['item_name']}"
+    # Add your custom logic here
+  end
+
+  def handle_inventory_updated(data)
+    puts "Inventory updated for variant: #{data['variant_id']}"
+    puts "New stock level: #{data['in_stock']}"
+    # Add your custom logic here
+  end
+end
+
+# Create and start the server
+port = ENV['PORT'] || 3000
+server = WEBrick::HTTPServer.new(Port: port)
+
+server.mount '/webhooks/loyverse', WebhookHandler, client
+
+trap('INT') { server.shutdown }
+
+puts "Webhook server listening on port #{port}"
+puts "Webhook URL: http://localhost:#{port}/webhooks/loyverse"
+puts "Press Ctrl+C to stop"
+puts
+
+server.start

data/lib/loyverse_api/client.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module LoyverseApi
+  class Client
+    include Endpoints::Items
+    include Endpoints::Categories
+    include Endpoints::Inventory
+    include Endpoints::Receipts
+    include Endpoints::Webhooks
+    include Endpoints::Customers
+    include Endpoints::Discounts
+    include Endpoints::Employees
+    include Endpoints::Modifiers
+
+    attr_reader :configuration
+
+    def initialize(configuration = nil)
+      @configuration = configuration || LoyverseApi.configuration || Configuration.new
+
+      raise AuthenticationError, "Access token is required" if @configuration.access_token.nil?
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: configuration.base_url) do |conn|
+        conn.request :json
+        conn.request :retry, {
+          max: 3,
+          interval: 0.5,
+          interval_randomness: 0.5,
+          backoff_factor: 2,
+          retry_statuses: [429, 500, 502, 503, 504],
+          methods: [:get, :post, :put, :delete]
+        }
+        conn.response :json, content_type: /\bjson$/
+        conn.headers['Authorization'] = "Bearer #{configuration.access_token}"
+        conn.headers['Content-Type'] = 'application/json'
+        conn.headers['Accept'] = 'application/json'
+        conn.adapter Faraday.default_adapter
+        conn.options.timeout = configuration.timeout
+        conn.options.open_timeout = configuration.open_timeout
+      end
+    end
+
+    def get(path, params: {})
+      handle_response do
+        response = connection.get(path, params)
+        response
+      end
+    end
+
+    def post(path, body: {})
+      handle_response do
+        response = connection.post(path, body)
+        response
+      end
+    end
+
+    def put(path, body: {})
+      handle_response do
+        response = connection.put(path, body)
+        response
+      end
+    end
+
+    def delete(path)
+      handle_response do
+        response = connection.delete(path)
+        response
+      end
+    end
+
+    private
+
+    def handle_response
+      response = yield
+
+      case response.status
+      when 200, 201, 204
+        response.body
+      when 400
+        raise BadRequestError.new(
+          error_message(response) || "Bad Request: #{response.body.inspect}",
+          code: error_code(response),
+          details: error_details(response)
+        )
+      when 401
+        raise AuthenticationError.new(
+          error_message(response),
+          code: error_code(response),
+          details: error_details(response)
+        )
+      when 403
+        raise AuthorizationError.new(
+          error_message(response),
+          code: error_code(response),
+          details: error_details(response)
+        )
+      when 404
+        raise NotFoundError.new(
+          error_message(response),
+          code: error_code(response),
+          details: error_details(response)
+        )
+      when 429
+        raise RateLimitError.new(
+          error_message(response) || "Rate limit exceeded",
+          code: error_code(response),
+          details: error_details(response)
+        )
+      when 500, 502, 503, 504
+        raise ServerError.new(
+          error_message(response) || "Server error occurred",
+          code: error_code(response),
+          details: error_details(response)
+        )
+      else
+        raise ApiError.new(
+          error_message(response) || "Unknown error occurred",
+          code: error_code(response),
+          details: error_details(response)
+        )
+      end
+    rescue Faraday::TimeoutError
+      raise Error, "Request timeout"
+    rescue Faraday::ConnectionFailed
+      raise Error, "Connection failed"
+    end
+
+    def error_message(response)
+      return nil unless response.body.is_a?(Hash)
+      response.body.dig("error", "message") || response.body["message"]
+    end
+
+    def error_code(response)
+      return nil unless response.body.is_a?(Hash)
+      response.body.dig("error", "code")
+    end
+
+    def error_details(response)
+      return nil unless response.body.is_a?(Hash)
+      response.body.dig("error", "details")
+    end
+
+    def format_time(time)
+      return nil if time.nil?
+      return time if time.is_a?(String)
+
+      if time.respond_to?(:strftime) && !time.respond_to?(:hour)
+        return "#{time.strftime('%Y-%m-%d')}T00:00:00.000Z"
+      end
+
+      return time.utc.strftime('%Y-%m-%dT%H:%M:%S.%LZ') if time.respond_to?(:utc)
+
+      time
+    end
+  end
+end

data/lib/loyverse_api/configuration.rb

@@ -0,0 +1,13 @@
+module LoyverseApi
+  class Configuration
+    attr_accessor :access_token, :api_base_url, :timeout, :open_timeout
+    alias_method :base_url, :api_base_url
+
+    def initialize
+      @api_base_url = "https://api.loyverse.com/v1.0/"
+      @timeout = 30
+      @open_timeout = 10
+      @access_token = nil
+    end
+  end
+end

data/lib/loyverse_api/endpoints/categories.rb

@@ -0,0 +1,43 @@
+module LoyverseApi
+  module Endpoints
+    module Categories
+      # Get a specific category by ID
+      # @param category_id [String] UUID of the category
+      # @return [Hash] Category details
+      def get_category(category_id)
+        get("categories/#{category_id}")
+      end
+
+      # List all categories
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @return [Hash] Response with categories array
+      def list_categories(limit: 250, cursor: nil)
+        params = {
+          limit: limit,
+          cursor: cursor
+        }.compact
+
+        get("categories", params: params)
+      end
+
+      # Create a new category
+      # @param name [String] Category name
+      # @param color [String] Color code (e.g., "ORANGE", "RED", "BLUE")
+      # @return [Hash] Created category details
+      def create_category(name:, color: nil)
+        body = { name: name }
+        body[:color] = color if color
+
+        post("categories", body: body)
+      end
+
+      # Delete a category
+      # @param category_id [String] UUID of the category
+      # @return [Hash] Response
+      def delete_category(category_id)
+        delete("categories/#{category_id}")
+      end
+    end
+  end
+end

data/lib/loyverse_api/endpoints/customers.rb

@@ -0,0 +1,131 @@
+module LoyverseApi
+  module Endpoints
+    module Customers
+      # Get a specific customer by ID
+      # @param customer_id [String] UUID of the customer
+      # @return [Hash] Customer details
+      def get_customer(customer_id)
+        get("customers/#{customer_id}")
+      end
+
+      # List customers
+      # @param limit [Integer] Maximum number of results per page (default: 250)
+      # @param cursor [String] Pagination cursor for next page
+      # @param email [String] Filter by email address (optional)
+      # @param phone_number [String] Filter by phone number (optional)
+      # @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 customers array
+      def list_customers(limit: 250, cursor: nil, email: nil, phone_number: nil, updated_at_min: nil, updated_at_max: nil)
+        params = {
+          limit: limit,
+          cursor: cursor,
+          email: email,
+          phone_number: phone_number,
+          updated_at_min: format_time(updated_at_min),
+          updated_at_max: format_time(updated_at_max)
+        }.compact
+
+        get("customers", params: params)
+      end
+
+      # Create a new customer
+      # @param name [String] Customer name
+      # @param email [String] Customer email (optional)
+      # @param phone_number [String] Customer phone number (optional)
+      # @param address [String] Customer address (optional)
+      # @param city [String] Customer city (optional)
+      # @param region [String] Customer region/state (optional)
+      # @param postal_code [String] Customer postal code (optional)
+      # @param country [String] Customer country (optional)
+      # @param customer_code [String] Custom customer code (optional)
+      # @param note [String] Customer note (optional)
+      # @param first_visit [String, Time] Date of first visit (optional)
+      # @param total_visits [Integer] Total number of visits (optional)
+      # @param total_spent [Float] Total amount spent (optional)
+      # @return [Hash] Created customer details
+      def create_customer(
+        name:,
+        email: nil,
+        phone_number: nil,
+        address: nil,
+        city: nil,
+        region: nil,
+        postal_code: nil,
+        country: nil,
+        customer_code: nil,
+        note: nil,
+        first_visit: nil,
+        total_visits: nil,
+        total_spent: nil
+      )
+        body = {
+          name: name,
+          email: email,
+          phone_number: phone_number,
+          address: address,
+          city: city,
+          region: region,
+          postal_code: postal_code,
+          country: country,
+          customer_code: customer_code,
+          note: note,
+          first_visit: format_time(first_visit),
+          total_visits: total_visits,
+          total_spent: total_spent
+        }.compact
+
+        post("customers", body: body)
+      end
+
+      # Update an existing customer
+      # @param customer_id [String] UUID of the customer
+      # @param name [String] Customer name (optional)
+      # @param email [String] Customer email (optional)
+      # @param phone_number [String] Customer phone number (optional)
+      # @param address [String] Customer address (optional)
+      # @param city [String] Customer city (optional)
+      # @param region [String] Customer region/state (optional)
+      # @param postal_code [String] Customer postal code (optional)
+      # @param country [String] Customer country (optional)
+      # @param customer_code [String] Custom customer code (optional)
+      # @param note [String] Customer note (optional)
+      # @return [Hash] Updated customer details
+      def update_customer(
+        customer_id,
+        name: nil,
+        email: nil,
+        phone_number: nil,
+        address: nil,
+        city: nil,
+        region: nil,
+        postal_code: nil,
+        country: nil,
+        customer_code: nil,
+        note: nil
+      )
+        body = {
+          name: name,
+          email: email,
+          phone_number: phone_number,
+          address: address,
+          city: city,
+          region: region,
+          postal_code: postal_code,
+          country: country,
+          customer_code: customer_code,
+          note: note
+        }.compact
+
+        put("customers/#{customer_id}", body: body)
+      end
+
+      # Delete a customer
+      # @param customer_id [String] UUID of the customer
+      # @return [Hash] Response
+      def delete_customer(customer_id)
+        delete("customers/#{customer_id}")
+      end
+    end
+  end
+end