cin7_core_api 0.2.0

data/lib/cin7_core_api/redactor.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Cin7CoreAPI
+  # Only sanitized copies leave the transport. Never mutate a caller's payload.
+  class Redactor
+    FILTERED = "[FILTERED]"
+    SENSITIVE_KEY = /authorization|authentication|password|passwd|secret|token|cookie|apikey|applicationkey|apiauthaccountid|externalusername/i
+    GUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+    HTTP_URL = %r{\A(https?://)([^/?#]*)([^?#]*)(?:\?([^#]*))?(?:\#(.*))?\z}i
+
+    def initialize(secrets = [])
+      @secrets = secrets.grep(String).reject(&:empty?).uniq.sort_by { |value| -value.length }.map { |value| value.dup.freeze }.freeze
+    end
+
+    def with_sensitive_values(value)
+      self.class.new(@secrets + sensitive_values(value))
+    end
+
+    def filter(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, entry), result|
+          # Field names are schema, even when a credential happens to match one.
+          result[key.to_s] = if sensitive_key?(key) || external_headers?(key)
+            FILTERED
+          elsif callback_url?(key) && entry.is_a?(String)
+            filter_url(entry)
+          elsif structured_identifier?(key, entry)
+            # Short header values must not corrupt identifiers or schema enums.
+            @secrets.include?(entry) ? FILTERED : entry.dup
+          else
+            filter(entry)
+          end
+        end
+      when Array
+        value.map { |entry| filter(entry) }
+      when String
+        filter_string(value)
+      else
+        value
+      end
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    private
+
+    def sensitive_key?(key)
+      normalized = normalized_key(key)
+      # AccountID and BankAccountId identify business records, not API access.
+      # The authentication header is api-auth-accountid; known credential values
+      # are still filtered wherever they occur, including business ID fields.
+      normalized != "externalauthorizationtype" && normalized.match?(SENSITIVE_KEY)
+    end
+
+    def normalized_key(key)
+      key.to_s.gsub(/[^a-z0-9]/i, "").downcase
+    end
+
+    def external_headers?(key)
+      normalized_key(key) == "externalheaders"
+    end
+
+    def callback_url?(key)
+      normalized_key(key) == "externalurl"
+    end
+
+    def structured_identifier?(key, value)
+      value.is_a?(String) && ((normalized_key(key).end_with?("id") && GUID.match?(value)) ||
+        %w[type externalauthorizationtype].include?(normalized_key(key)))
+    end
+
+    def sensitive_values(value)
+      case value
+      when Hash
+        value.flat_map do |key, entry|
+          if external_headers?(key)
+            Array(entry).flat_map { |header| header.is_a?(Hash) ? strings_in(header["Value"] || header[:Value] || header["value"]) : [] }
+          elsif sensitive_key?(key)
+            strings_in(entry)
+          elsif callback_url?(key) && entry.is_a?(String)
+            url_credentials(entry)
+          else
+            sensitive_values(entry)
+          end
+        end
+      when Array
+        value.flat_map { |entry| sensitive_values(entry) }
+      else
+        []
+      end
+    end
+
+    def strings_in(value)
+      case value
+      when Hash then value.values.flat_map { |entry| strings_in(entry) }
+      when Array then value.flat_map { |entry| strings_in(entry) }
+      when String then [value, value.sub(/\A(?:Bearer|Basic)\s+/i, "")]
+      else []
+      end
+    end
+
+    def sensitive_query_key?(key)
+      sensitive_key?(key) || %w[accountid username user auth key signature sig].include?(normalized_key(key))
+    end
+
+    def url_credentials(value)
+      url = URI.parse(value)
+      return [] unless url.is_a?(URI::HTTP) && url.host
+
+      credentials = url.userinfo.to_s.split(":", 2).flat_map { |part| [part, URI::DEFAULT_PARSER.unescape(part)] }
+      [url.query, url.fragment].compact.each do |query|
+        query.split(/[&;]/).each do |part|
+          key, separator, entry = part.partition("=")
+          if !separator.empty? && sensitive_query_key?(URI.decode_www_form_component(key))
+            credentials.concat([entry, URI.decode_www_form_component(entry)])
+          end
+        end
+      end
+      strings_in(credentials)
+    rescue URI::InvalidURIError, ArgumentError
+      []
+    end
+
+    def filter_url(value)
+      return FILTERED if @secrets.include?(value)
+
+      url = URI.parse(value)
+      return FILTERED unless url.is_a?(URI::HTTP) && url.host
+
+      # Keep spelling, escaping, parameter order and delimiters intact. Rebuilding
+      # a URI or substring-filtering it can change callback ownership comparisons.
+      scheme, authority, path, query, fragment = HTTP_URL.match(value).captures
+      authority = filter_authority(authority, url.host)
+      path = path.split("/", -1).map { |part| filter_url_component(part) }.join("/")
+      result = "#{scheme}#{authority}#{path}"
+      result += "?#{filter_query(query)}" unless query.nil?
+      result += "##{filter_query(fragment)}" unless fragment.nil?
+      result
+    rescue URI::InvalidURIError, ArgumentError
+      FILTERED
+    end
+
+    def filter_authority(authority, host)
+      _, separator, host_port = authority.rpartition("@")
+      filtered_host = filter_url_component(host)
+      if filtered_host != FILTERED
+        filtered_host = host.split(".", -1).map { |part| filter_url_component(part) }.join(".")
+      end
+      filtered = host_port.sub(host) { filtered_host }
+      separator.empty? ? filtered : "#{FILTERED}@#{filtered}"
+    end
+
+    def filter_query(query)
+      query.split(/([&;])/, -1).map do |part|
+        key, separator, entry = part.partition("=")
+        if separator.empty?
+          filter_url_component(key, form: true)
+        else
+          filtered = sensitive_query_key?(URI.decode_www_form_component(key)) ? FILTERED : filter_url_component(entry, form: true)
+          "#{filter_url_component(key, form: true)}=#{filtered}"
+        end
+      end.join
+    end
+
+    def filter_url_component(value, form: false)
+      decoded = form ? URI.decode_www_form_component(value) : URI::DEFAULT_PARSER.unescape(value)
+      (@secrets.include?(value) || @secrets.include?(decoded)) ? FILTERED : value
+    end
+
+    def filter_string(value)
+      filtered = @secrets.reduce(value.dup) { |text, secret| text.gsub(secret, FILTERED) }
+      filtered = filtered.gsub(%r{(https?://)[^\s/@]+:[^\s/@]+@}i, "\\1#{FILTERED}@")
+      # Non-JSON error bodies may echo credentials as header or form text.
+      filtered = filtered.gsub(/\b(Bearer|Basic)\s+[^\s,"'<>]+/i, "\\1 #{FILTERED}")
+      filtered.gsub(/([\w-]*(?:password|passwd|secret|token|authorization|api[-_]?key|application[-_]?key|account[-_]?id)[\w-]*["']?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;&<>]+)/i, "\\1#{FILTERED}")
+    end
+  end
+end

data/lib/cin7_core_api/resources/accounts.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Accounts < Base
+      PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        code: "Code",
+        name: "Name",
+        type: "Type",
+        status: "Status"
+      }.freeze
+
+      def list(**filters)
+        get("ref/account", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/bank_accounts.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class BankAccounts < Base
+      PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        id: "ID",
+        name: "Name",
+        bank: "Bank"
+      }.freeze
+
+      def list(**filters)
+        get("ref/account/bank", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Base
+      attr_reader :connection
+
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def inspect
+        "#<#{self.class}>"
+      end
+
+      private
+
+      def get(path, params: {}, parameter_map: {})
+        connection.get(path, params: map_parameters(params, parameter_map))
+      end
+
+      def validate_payload!(payload, *identifiers)
+        unless payload.is_a?(Hash) && payload.keys.all? { |key| key.is_a?(String) }
+          raise ArgumentError, "payload must be a Hash with Cin7 JSON field names as String keys"
+        end
+
+        identifiers.each { |name| require_parameter!(name, payload[name]) }
+      end
+
+      def map_parameters(params, parameter_map)
+        unknown = params.keys - parameter_map.keys
+        unless unknown.empty?
+          raise ArgumentError, "Unknown parameters: #{unknown.sort.join(", ")}"
+        end
+
+        params.each_with_object({}) do |(key, value), mapped|
+          mapped[parameter_map.fetch(key)] = value unless value.nil?
+        end
+      end
+
+      def require_parameter!(name, value)
+        missing = value.nil? || (value.is_a?(String) ? value.strip.empty? : value.respond_to?(:empty?) && value.empty?)
+        return unless missing
+
+        raise ArgumentError, "#{name} is required"
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/credit_notes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class CreditNotes < Base
+      LIST_PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        search: "Search",
+        created_since: "CreatedSince",
+        updated_since: "UpdatedSince",
+        updated_until: "UpdatedUntil",
+        credit_note_status: "CreditNoteStatus",
+        status: "Status"
+      }.freeze
+
+      FOR_SALE_PARAMETERS = {
+        sale_id: "SaleID",
+        combine_additional_charges: "CombineAdditionalCharges",
+        include_product_info: "IncludeProductInfo",
+        include_payment_info: "IncludePaymentInfo"
+      }.freeze
+
+      def list(**filters)
+        get("saleCreditNoteList", params: filters, parameter_map: LIST_PARAMETERS)
+      end
+
+      def for_sale(sale_id:, **options)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/creditnote", params: options.merge(sale_id: sale_id), parameter_map: FOR_SALE_PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/customer_credits.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class CustomerCredits < Base
+      PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        customer_id: "CustomerID",
+        show_used_credits: "ShowUsedCredits"
+      }.freeze
+
+      def list(**filters)
+        get("ref/customer/credits", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/customers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Customers < Base
+      PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        id: "ID",
+        name: "Name",
+        modified_since: "ModifiedSince",
+        include_deprecated: "IncludeDeprecated",
+        include_product_prices: "IncludeProductPrices",
+        contact_filter: "ContactFilter"
+      }.freeze
+
+      def list(**filters)
+        get("customer", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/invoices.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Invoices < Base
+      PARAMETERS = {
+        sale_id: "SaleID",
+        combine_additional_charges: "CombineAdditionalCharges",
+        include_product_info: "IncludeProductInfo"
+      }.freeze
+
+      def for_sale(sale_id:, **options)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/invoice", params: options.merge(sale_id: sale_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID", "TaskID")
+        connection.post("sale/invoice", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "SaleID", "TaskID")
+        connection.put("sale/invoice", payload: payload)
+      end
+
+      def undo(task_id:)
+        require_parameter!(:task_id, task_id)
+        connection.delete("sale/invoice", params: {"TaskID" => task_id, "Void" => false})
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/journals.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Journals < Base
+      PARAMETERS = {
+        page: "Page", limit: "Limit", task_id: "TaskID", status: "Status", search: "Search"
+      }.freeze
+
+      def list(**filters)
+        get("journal", params: filters, parameter_map: PARAMETERS)
+      end
+
+      def retrieve(task_id:)
+        require_parameter!(:task_id, task_id)
+        list(task_id: task_id)
+      end
+
+      def create(payload:)
+        validate_payload!(payload)
+        connection.post("journal", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("journal", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/locations.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Locations < Base
+      PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        id: "ID",
+        deprecated: "Deprecated",
+        name: "Name"
+      }.freeze
+
+      def list(**filters)
+        get("ref/location", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/manual_journals.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class ManualJournals < Base
+      def for_sale(sale_id:)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/manualJournal", params: {sale_id: sale_id}, parameter_map: {sale_id: "SaleID"})
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID")
+        connection.post("sale/manualJournal", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/me.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Me < Base
+      def retrieve
+        get("me")
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/orders.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Orders < Base
+      PARAMETERS = {
+        sale_id: "SaleID",
+        combine_additional_charges: "CombineAdditionalCharges",
+        include_product_info: "IncludeProductInfo"
+      }.freeze
+
+      def for_sale(sale_id:, **options)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/order", params: options.merge(sale_id: sale_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID")
+        connection.post("sale/order", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/payments.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Payments < Base
+      PARAMETERS = {sale_id: "SaleID"}.freeze
+
+      def for_sale(sale_id:)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/payment", params: {sale_id: sale_id}, parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/payment", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "ID")
+        connection.put("sale/payment", payload: payload)
+      end
+
+      def delete(id:)
+        require_parameter!(:id, id)
+        connection.delete("sale/payment", params: {"ID" => id})
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/sales.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Sales < Base
+      LIST_PARAMETERS = {
+        page: "Page",
+        limit: "Limit",
+        search: "Search",
+        created_since: "CreatedSince",
+        updated_since: "UpdatedSince",
+        updated_until: "UpdatedUntil",
+        ship_by: "ShipBy",
+        quote_status: "QuoteStatus",
+        order_status: "OrderStatus",
+        combined_pick_status: "CombinedPickStatus",
+        combined_pack_status: "CombinedPackStatus",
+        combined_shipping_status: "CombinedShippingStatus",
+        combined_invoice_status: "CombinedInvoiceStatus",
+        credit_note_status: "CreditNoteStatus",
+        external_id: "ExternalID",
+        status: "Status",
+        ready_for_shipping: "ReadyForShipping",
+        order_location_id: "OrderLocationID"
+      }.freeze
+
+      RETRIEVE_PARAMETERS = {
+        id: "ID",
+        combine_additional_charges: "CombineAdditionalCharges",
+        hide_inventory_movements: "HideInventoryMovements",
+        include_transactions: "IncludeTransactions",
+        country_format: "CountryFormat"
+      }.freeze
+
+      def list(**filters)
+        get("saleList", params: filters, parameter_map: LIST_PARAMETERS)
+      end
+
+      def retrieve(id:, **options)
+        require_parameter!(:id, id)
+        get("sale", params: options.merge(id: id), parameter_map: RETRIEVE_PARAMETERS)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "ID")
+        connection.put("sale", payload: payload)
+      end
+
+      def undo(id:)
+        require_parameter!(:id, id)
+        connection.delete("sale", params: {"ID" => id, "Void" => false})
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/tax_rules.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class TaxRules < Base
+      PARAMETERS = {
+        page: "Page", limit: "Limit", id: "ID", name: "Name", is_active: "IsActive",
+        is_tax_for_sale: "IsTaxForSale", is_tax_for_purchase: "IsTaxForPurchase", account: "Account"
+      }.freeze
+
+      def list(**filters)
+        get("ref/tax", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/webhooks.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Webhooks < Base
+      def list
+        get("webhooks")
+      end
+
+      def create(payload:)
+        validate_payload!(payload)
+        connection.post("webhooks", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "ID")
+        connection.put("webhooks", payload: payload)
+      end
+
+      def delete(id:)
+        require_parameter!(:id, id)
+        connection.delete("webhooks", params: {"ID" => id})
+      end
+    end
+  end
+end

data/lib/cin7_core_api/response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  class Response
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers:, body:)
+      @status = status
+      @headers = headers.freeze
+      @body = body
+      freeze
+    end
+
+    def success?
+      (200..299).cover?(status)
+    end
+
+    def no_content?
+      status == 204 || body.nil?
+    end
+
+    def inspect
+      "#<#{self.class} status=#{status}>"
+    end
+  end
+end

data/lib/cin7_core_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  VERSION = "0.2.0"
+end

data/lib/cin7_core_api.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "cin7_core_api/version"
+require_relative "cin7_core_api/errors"
+require_relative "cin7_core_api/response"
+require_relative "cin7_core_api/redactor"
+require_relative "cin7_core_api/connection"
+require_relative "cin7_core_api/resources/base"
+require_relative "cin7_core_api/resources/me"
+require_relative "cin7_core_api/resources/sales"
+require_relative "cin7_core_api/resources/credit_notes"
+require_relative "cin7_core_api/resources/payments"
+require_relative "cin7_core_api/resources/locations"
+require_relative "cin7_core_api/resources/accounts"
+require_relative "cin7_core_api/resources/bank_accounts"
+require_relative "cin7_core_api/resources/customers"
+require_relative "cin7_core_api/resources/customer_credits"
+require_relative "cin7_core_api/resources/orders"
+require_relative "cin7_core_api/resources/invoices"
+require_relative "cin7_core_api/resources/manual_journals"
+require_relative "cin7_core_api/resources/journals"
+require_relative "cin7_core_api/resources/tax_rules"
+require_relative "cin7_core_api/resources/webhooks"
+require_relative "cin7_core_api/client"
+
+module Cin7CoreAPI
+end