cashctrl 0.0.1 → 0.1.0

data/lib/cashctrl/client.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Cashctrl
+  class Client
+    attr_reader :config
+
+    def initialize(org: nil, api_key: nil, language: "en")
+      @config = Configuration.new
+      @config.org = org
+      @config.api_key = api_key
+      @config.language = language
+    end
+
+    def connection
+      @connection ||= build_connection
+    end
+
+    def get(path, params = {})
+      params = params.merge(lang: config.language) if config.language
+      response = connection.get(path, params)
+      handle_response(response)
+    end
+
+    def post(path, params = {})
+      params = params.merge(lang: config.language) if config.language
+      response = connection.post(path, params)
+      handle_response(response)
+    end
+
+    def get_raw(path, params = {})
+      params = params.merge(lang: config.language) if config.language
+      response = raw_connection.get(path, params)
+      handle_raw_response(response)
+    end
+
+    def accounts
+      Resources::Account.new(self)
+    end
+
+    def account_categories
+      Resources::Account::Category.new(self)
+    end
+
+    def account_cost_centers
+      Resources::Account::CostCenter.new(self)
+    end
+
+    def bank_accounts
+      Resources::Account::Bank.new(self)
+    end
+
+    def currencies
+      Resources::Currency.new(self)
+    end
+
+    def custom_fields
+      Resources::CustomField.new(self)
+    end
+
+    def files
+      Resources::CashctrlFile.new(self)
+    end
+
+    def file_categories
+      Resources::CashctrlFile::Category.new(self)
+    end
+
+    def fiscal_periods
+      Resources::FiscalPeriod.new(self)
+    end
+
+    def inventory_articles
+      Resources::Inventory::Article.new(self)
+    end
+
+    def inventory_assets
+      Resources::Inventory::Asset.new(self)
+    end
+
+    def inventory_units
+      Resources::Inventory::Unit.new(self)
+    end
+
+    def journal_entries
+      Resources::Journal.new(self)
+    end
+
+    def locations
+      Resources::Location.new(self)
+    end
+
+    def orders
+      Resources::Order.new(self)
+    end
+
+    def order_categories
+      Resources::Order::Category.new(self)
+    end
+
+    def order_documents
+      Resources::Order::Document.new(self)
+    end
+
+    def persons
+      Resources::Person.new(self)
+    end
+
+    def person_categories
+      Resources::Person::Category.new(self)
+    end
+
+    def person_titles
+      Resources::Person::Title.new(self)
+    end
+
+    def reports
+      Resources::Report.new(self)
+    end
+
+    def roundings
+      Resources::Rounding.new(self)
+    end
+
+    def sequence_numbers
+      Resources::SequenceNumber.new(self)
+    end
+
+    def settings
+      Resources::Setting.new(self)
+    end
+
+    def taxes
+      Resources::Tax.new(self)
+    end
+
+    def texts
+      Resources::Text.new(self)
+    end
+
+    private
+
+    def build_connection
+      config.validate!
+
+      Faraday.new(url: config.base_url) do |f|
+        f.request :url_encoded
+        f.request :authorization, :basic, config.api_key, ""
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def raw_connection
+      @raw_connection ||= begin
+        config.validate!
+
+        Faraday.new(url: config.base_url) do |f|
+          f.request :url_encoded
+          f.request :authorization, :basic, config.api_key, ""
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200
+        handle_success_response(response)
+      when 401
+        raise AuthenticationError.new("Invalid API key", response: response)
+      when 404
+        raise NotFoundError.new("Resource not found", response: response)
+      when 429
+        raise RateLimitError.new("Rate limit exceeded", response: response)
+      when 500..599
+        raise ServerError.new("Server error: #{response.status}", response: response)
+      else
+        raise Error.new("Unexpected response: #{response.status}", response: response)
+      end
+    end
+
+    def handle_success_response(response)
+      body = response.body
+
+      return body unless body.is_a?(Hash)
+
+      if body["success"] == false
+        errors = body["errors"] || []
+        message = body["message"] || errors.map { |e| e["message"] }.join(", ")
+        raise ValidationError.new(message, errors: errors, response: response)
+      end
+
+      body
+    end
+
+    def handle_raw_response(response)
+      case response.status
+      when 200
+        response.body
+      when 401
+        raise AuthenticationError.new("Invalid API key", response: response)
+      when 404
+        raise NotFoundError.new("Resource not found", response: response)
+      when 429
+        raise RateLimitError.new("Rate limit exceeded", response: response)
+      when 500..599
+        raise ServerError.new("Server error: #{response.status}", response: response)
+      else
+        raise Error.new("Unexpected response: #{response.status}", response: response)
+      end
+    end
+  end
+end

data/lib/cashctrl/collection.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Cashctrl
+  class Collection
+    include Enumerable
+
+    attr_reader :data, :total, :summary, :properties, :resource_class
+
+    def self.from_response(response, resource_class: Resource)
+      data = response.is_a?(Array) ? response : (response["data"] || [])
+
+      new(
+        data: data,
+        total: response.is_a?(Hash) ? response["total"] : nil,
+        summary: response.is_a?(Hash) ? response["summary"] : nil,
+        properties: response.is_a?(Hash) ? response["properties"] : nil,
+        resource_class: resource_class
+      )
+    end
+
+    def initialize(data:, total: nil, summary: nil, properties: nil, resource_class: Resource)
+      @resource_class = resource_class
+      @data = data.map { |item| resource_class.from_response(item) }
+      @total = total || @data.size
+      @summary = summary
+      @properties = properties
+    end
+
+    def each(&)
+      @data.each(&)
+    end
+
+    def size
+      @data.size
+    end
+
+    alias length size
+    alias count size
+
+    def empty?
+      @data.empty?
+    end
+
+    def first
+      @data.first
+    end
+
+    def last
+      @data.last
+    end
+
+    def [](index)
+      @data[index]
+    end
+
+    def to_a
+      @data.dup
+    end
+
+    def to_h
+      {
+        "data" => @data.map(&:to_h),
+        "total" => @total,
+        "summary" => @summary,
+        "properties" => @properties,
+      }
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    def inspect
+      "#<#{self.class.name} total=#{@total} size=#{size} resource_class=#{@resource_class.name}>"
+    end
+  end
+end

data/lib/cashctrl/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cashctrl
+  class Configuration
+    attr_accessor :org, :api_key, :language
+
+    def initialize
+      @org = ENV.fetch("CASHCTRL_ORG", nil)
+      @api_key = ENV.fetch("CASHCTRL_API_KEY", nil)
+      @language = ENV.fetch("CASHCTRL_LANGUAGE", "en")
+    end
+
+    def base_url
+      raise ConfigurationError, "org must be configured" if org.nil? || org.empty?
+
+      "https://#{org}.cashctrl.com/api/v1"
+    end
+
+    def valid?
+      !org.nil? && !org.empty? && !api_key.nil? && !api_key.empty?
+    end
+
+    def validate! # rubocop:disable Naming/PredicateMethod
+      raise ConfigurationError, "org must be configured" if org.nil? || org.empty?
+      raise ConfigurationError, "api_key must be configured" if api_key.nil? || api_key.empty?
+
+      true
+    end
+  end
+end

data/lib/cashctrl/error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Cashctrl
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: [], response: nil)
+      @errors = errors
+      super(message, response: response)
+    end
+  end
+end

data/lib/cashctrl/localized_string.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+
+module Cashctrl
+  class LocalizedString
+    LOCALIZED_PATTERN = %r{<values>.*?</values>}m
+
+    attr_reader :translations, :raw, :prefix
+
+    def self.localized?(value)
+      return false unless value.is_a?(String)
+
+      value.match?(LOCALIZED_PATTERN)
+    end
+
+    def self.parse(value)
+      return value unless localized?(value)
+
+      new(value)
+    end
+
+    def initialize(xml_string)
+      @translations = {}
+      @raw = xml_string
+      @prefix = ""
+
+      parse_xml(xml_string)
+    end
+
+    def [](locale)
+      value = @translations[locale.to_s.downcase]
+      return nil unless value
+
+      @prefix.empty? ? value : "#{@prefix}#{value}"
+    end
+
+    def to_s
+      current_locale = if defined?(I18n) && I18n.respond_to?(:locale)
+                         I18n.locale.to_s.downcase
+                       else
+                         Cashctrl.configuration&.language&.downcase || "en"
+                       end
+
+      value = @translations[current_locale] || @translations["en"] || @translations.values.first
+      return @raw unless value
+
+      @prefix.empty? ? value : "#{@prefix}#{value}"
+    end
+
+    def to_h
+      @translations.dup
+    end
+
+    def inspect
+      if @prefix.empty?
+        "#<#{self.class.name} #{@translations.inspect}>"
+      else
+        "#<#{self.class.name} prefix=#{@prefix.inspect} #{@translations.inspect}>"
+      end
+    end
+
+    def ==(other)
+      case other
+      when LocalizedString
+        @translations == other.translations
+      when String
+        to_s == other
+      else
+        false
+      end
+    end
+
+    alias eql? ==
+
+    def hash
+      @translations.hash
+    end
+
+    def method_missing(method_name, *args)
+      locale = method_name.to_s.downcase
+
+      if @translations.key?(locale)
+        value = @translations[locale]
+        @prefix.empty? ? value : "#{@prefix}#{value}"
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @translations.key?(method_name.to_s.downcase) || super
+    end
+
+    private
+
+    def parse_xml(xml_string)
+      match = xml_string.match(LOCALIZED_PATTERN)
+
+      return unless match
+
+      @prefix = xml_string[0...match.begin(0)]
+      values_xml = match[0]
+
+      doc = REXML::Document.new(values_xml)
+
+      doc.root&.elements&.each do |element|
+        locale = element.name.downcase
+        @translations[locale] = element.text || ""
+      end
+    rescue REXML::ParseException
+      @translations["raw"] = xml_string
+    end
+  end
+end

data/lib/cashctrl/models/account.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class Account < Resource
+      attribute :category_id, type: :integer
+      attribute :category_display, type: :string, readonly: true
+      attribute :account_class, type: :string
+      attribute :tax_id, type: :integer
+      attribute :tax_name, type: :string, readonly: true
+      attribute :currency_id, type: :integer
+      attribute :currency_code, type: :string
+      attribute :number, type: :string
+      attribute :name, type: :string
+      attribute :custom, type: :string
+      attribute :notes, type: :string
+      attribute :attachment_count, type: :integer, readonly: true
+      attribute :allocation_count, type: :integer, readonly: true
+      attribute :cost_center_ids, type: :string
+      attribute :cost_center_numbers, type: :string, readonly: true
+      attribute :opening_amount, type: :decimal
+      attribute :end_amount, type: :decimal, readonly: true
+      attribute :target_min, type: :decimal
+      attribute :target_max, type: :decimal
+      attribute :target_display, type: :string, readonly: true
+      attribute :default_currency_opening_amount, type: :decimal, readonly: true
+      attribute :default_currency_end_amount, type: :decimal, readonly: true
+      attribute :is_inactive, type: :boolean
+      attribute :is_in_salary_type, type: :boolean, readonly: true
+      attribute :is_bank_account, type: :boolean, readonly: true
+    end
+  end
+end

data/lib/cashctrl/models/article.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class Article < Resource
+      attribute :category_id, type: :integer
+      attribute :category_name, type: :string, readonly: true
+      attribute :nr, type: :string
+      attribute :name, type: :string
+      attribute :description, type: :string
+      attribute :unit_id, type: :integer
+      attribute :unit_name, type: :string, readonly: true
+      attribute :unit_price, type: :decimal
+      attribute :sales_account_id, type: :integer
+      attribute :sales_account_name, type: :string, readonly: true
+      attribute :purchase_account_id, type: :integer
+      attribute :purchase_account_name, type: :string, readonly: true
+      attribute :sales_tax_id, type: :integer
+      attribute :sales_tax_name, type: :string, readonly: true
+      attribute :purchase_tax_id, type: :integer
+      attribute :purchase_tax_name, type: :string, readonly: true
+      attribute :currency_id, type: :integer
+      attribute :currency_code, type: :string, readonly: true
+      attribute :last_purchase_price, type: :decimal, readonly: true
+      attribute :last_sales_price, type: :decimal, readonly: true
+      attribute :bin_location, type: :string
+      attribute :stock, type: :decimal
+      attribute :min_stock, type: :decimal
+      attribute :custom, type: :string
+      attribute :notes, type: :string
+      attribute :attachment_count, type: :integer, readonly: true
+      attribute :is_stock_article, type: :boolean
+      attribute :is_purchase_price_gross, type: :boolean
+      attribute :is_sales_price_gross, type: :boolean
+      attribute :is_inactive, type: :boolean
+    end
+  end
+end

data/lib/cashctrl/models/asset.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class Asset < Resource
+      attribute :category_id, type: :integer
+      attribute :category_name, type: :string, readonly: true
+      attribute :nr, type: :string
+      attribute :name, type: :string
+      attribute :date_acquired, type: :date
+      attribute :value_acquisition, type: :decimal
+      attribute :value_current, type: :decimal, readonly: true
+      attribute :value_depreciation, type: :decimal, readonly: true
+      attribute :value_salvage, type: :decimal
+      attribute :depreciation_type, type: :string
+      attribute :depreciation_rate, type: :decimal
+      attribute :useful_life, type: :integer
+      attribute :account_asset_id, type: :integer
+      attribute :account_asset_name, type: :string, readonly: true
+      attribute :account_depreciation_id, type: :integer
+      attribute :account_depreciation_name, type: :string, readonly: true
+      attribute :account_expense_id, type: :integer
+      attribute :account_expense_name, type: :string, readonly: true
+      attribute :custom, type: :string
+      attribute :notes, type: :string
+      attribute :attachment_count, type: :integer, readonly: true
+      attribute :is_inactive, type: :boolean
+    end
+  end
+end

data/lib/cashctrl/models/bank.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class Bank < Resource
+      attribute :account_id, type: :integer
+      attribute :account_name, type: :string, readonly: true
+      attribute :name, type: :string
+      attribute :iban, type: :string
+      attribute :bic, type: :string
+      attribute :qr_iban, type: :string
+    end
+  end
+end

data/lib/cashctrl/models/category.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class Category < Resource
+      attribute :parent_id, type: :integer
+      attribute :name, type: :string
+      attribute :sequence, type: :integer
+    end
+  end
+end

data/lib/cashctrl/models/certificate_document.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class CertificateDocument < Resource
+      attribute :certificate_id, type: :integer
+      attribute :layout_id, type: :integer
+      attribute :name, type: :string
+      attribute :file_id, type: :integer, readonly: true
+    end
+  end
+end

data/lib/cashctrl/models/certificate_template.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class CertificateTemplate < Resource
+      attribute :name, type: :string
+      attribute :year, type: :integer
+      attribute :fields, type: :json
+    end
+  end
+end

data/lib/cashctrl/models/cost_center.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class CostCenter < Resource
+      attribute :category_id, type: :integer
+      attribute :category_name, type: :string, readonly: true
+      attribute :number, type: :string
+      attribute :name, type: :string
+      attribute :notes, type: :string
+    end
+  end
+end

data/lib/cashctrl/models/currency.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class Currency < Resource
+      attribute :code, type: :string
+      attribute :description, type: :string
+      attribute :rate, type: :decimal
+      attribute :value, type: :string, readonly: true
+      attribute :index, type: :string, readonly: true
+      attribute :text, type: :string, readonly: true
+      attribute :is_default, type: :boolean
+      attribute :is_auto, type: :boolean
+    end
+  end
+end

data/lib/cashctrl/models/custom_field.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from schema.yml. Do not edit manually.
+
+module Cashctrl
+  module Models
+    class CustomField < Resource
+      attribute :type, type: :string
+      attribute :group_id, type: :integer
+      attribute :group_name, type: :string, readonly: true
+      attribute :name, type: :string
+      attribute :description, type: :string
+      attribute :data_type, type: :string
+      attribute :values, type: :string
+      attribute :is_multi, type: :boolean
+    end
+  end
+end