twinfieldrb 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7198d5041d60aeaa7150c2175b914f55a6f712eeed2607ea417bbfd59a40619
+  data.tar.gz: da01ddd6abd5bbf424b7caf8d124a270ab70f428c0a81e1359c2a9633b4e975b
+SHA512:
+  metadata.gz: b12687672b183120a1d21e6d931618993802da9ca80ded48b5a951b232a8e7e431e79c0af83199adb784ec4c7723dbf927615d4ecc4585ae76e6bc75c2bc65d7
+  data.tar.gz: 42c6c9be13b1e1fa4a07d49813504e1bd632d85c500476a8377412abde3a0d94cb11b8aa299760bb85e33eda3e4797a9ec1ab4039cda9e7cd0019bee971244ba

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,70 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master ]
+  schedule:
+    - cron: '23 6 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

data/.github/workflows/rspec.yml

@@ -0,0 +1,33 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Ruby CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-24.04
+
+    strategy:
+      matrix:
+        ruby-version: [ 3.1.6, 3.2.6, 3.3.6]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ${{ matrix.ruby-version }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+script/config.rb
+.project

data/.rspec

@@ -0,0 +1 @@
+--color

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All changes to the project will be documented in this file.
+
+## Pending release
+
+* [BREAKING] Ruby > 3
+* [BREAKING] Invoices are now what Twinfield calls SalesInvoices, not SalesTransactions
+* [FEATURE] Added different classes that act more like ruby native objects in the Twinfield domain, such as Twinfield::Customer, Twinfield::Invoice, Twinfield::Transaction and Twinfield::Browse::Transaction::Customer
+* [FEATURE] Allowed for OAuthSession; which is the preferred way of creating sessions
+* [BUGFIX] Finder code made to work
+
+## 0.0.x
+
+Initial releases by Ernst Rijsdijk, Stephan van Diepen and Joris Reijrink.

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in twinfield.gemspec
+gemspec

data/README.md

@@ -0,0 +1,120 @@
+# TwinfieldRB
+
+Twinfield is an international Web service for collaborative online accounting. The `twinfieldrb` gem is a simple client for their SOAP-based API (it is a continuation of the long forgotten `twinfield` gem)
+
+This project started as a clone of the `twinfield`-gem, but [I've been working](CHANGELOG.md) to abstract the soap calls away. Perhaps I'll release this as a gem on its own. For now see "Installing > Using Twinfield".
+
+## Installing
+
+### Using Twinfield
+
+Add Twinfield in `Gemfile` as a gem dependency:
+
+    gem "twinfieldrb", git: "https://github.com/murb/twinfield.git"
+
+Run the following in your console to install with Bundler:
+
+    bundle install
+
+For OAuth authentication, now the default As a companion gem a [`omniauth-twinfield`-gem](https://github.com/murb/omniauth-twinfield) was created to help setting up OAuth.
+
+## Configuration
+
+Your application will authenticate to Twinfield using OAuth. A companion gem was created to help setting up OAuth communication with your app: [`omniauth-twinfield`-gem](https://github.com/murb/omniauth-twinfield).
+
+Cluster and access token are retrieved in the OAuth flow:
+
+    Twinfield.configure do |config|
+      config.session_type = "Twinfield::Api::OAuthSession"
+      config.cluster = OAuthClient.last.token_data["twf.clusterUrl"]
+      config.access_token = OAuthClient.first.access_token
+      config.log_level = :debug
+    end
+
+    Twinfield::Request::List.offices
+
+Now configure the company you're looking for:
+
+    Twinfield.configuration.company="NL123"
+
+## Examples
+
+Here are some examples that may be useful when using this GEM for the first time.
+
+### List of all debtors
+
+    Twinfield::Request::List.dimensions({ dimtype: "DEB" })
+
+### Create a new debtor
+
+    debtor = Twinfield::Customer.new
+    debtor.code = Twinfield::Customer.next_unused_twinfield_customer_code # sorry
+    debtor.name = ""
+    debtor.shortname = ""
+    debtor.country = ""
+    debtor.banks = [Twinfield::Customer::Bank.new]
+    debtor.save
+
+### Create a new invoice
+
+    invoice = Twinfield::SalesInvoice.new(customer: 1003, invoicetype: "FACTUUR", currency: "EUR", invoicedate: Time.now, duedate: Time.now+1.month)
+    invoice.lines << Twinfield::SalesInvoice::Line.new(article: "A", unitspriceexcl: 100, allowdiscountorpremium: true, vatcode: "VH")
+    invoice.lines << Twinfield::SalesInvoice::Line.new(article: 0, unitspriceexcl: 100, description: "Spaartegoed", allowdiscountorpremium: true, vatcode: "VN")
+    invoice.lines << Twinfield::SalesInvoice::Line.new(article: 0, unitspriceexcl: 0, quantity: 0, description: "Custom article", allowdiscountorpremium: true, vatcode: "VH")
+
+    invoice.save
+
+### Read an invoice
+
+The following should be enough to
+
+    invoice = Twinfield::SalesInvoice.find(12, invoicetype: "FACTUUR")
+    invoice.lines # returns the lines
+    invoice.vat_lines # returns the vat lines
+    invoice.total # returns the total amount (derived)
+    invoice.customer # returns an Twinfield::Customer
+    invoice.invoice_address # returns the customer's invoice address (Twinfield::Customer::Address, not just a code)
+    invoice.delivery_address # returns the full delivery address (Twinfield::Customer::Address, not just a code)
+
+The matching transaction can be found using:
+
+    invoice.transaction
+
+### Find a transaction
+
+    transactions = Twinfield::Browse::Transaction::Customer.where(invoice_number: 12, code: "VRK")
+
+### Register a payment
+
+    trans = Twinfield::Transaction.new(code: "PIN", currency: "EUR")
+    trans.lines << Twinfield::Transaction::Line.new(type: :total, balance_code: "1230", value: 0.0, debitcredit: :debit)
+    trans.lines << Twinfield::Transaction::Line.new(type: :detail, balance_code: 1300, value: 60.5, debitcredit: :credit, customer_code: 1003, invoicenumber: 14)
+    trans.lines << Twinfield::Transaction::Line.new(type: :detail, balance_code: 1234, value: 60.5, debitcredit: :debit)
+    trans.save
+
+Now this payment can be matched against the invoice (if amounts match)):
+
+    trans.match!(Twinfield::Browse::Transaction::Customer.find(invoice_number: 14, code: "VRK"))
+
+### Get the transactions for a customer
+
+This gets a list of sales transactions for customer with code 1003
+
+    customer = Twinfield::Customer.find(1003)
+    customer.transactions(code: "VRK")
+
+### Store collect mandate
+
+    customer = Twinfield::Customer.find(1003)
+    customer.financials.collectmandate = Twinfield::Customer::CollectMandate.new(signaturedate: signed_on, id: sepa_proof_uuid)
+    customer.financials.payavailable = true # autosets meansofpayment to paymentfile; can be disabled to temporarily stop collecting through paymentfiles
+    customer.financials.paycode="SEPANLDD"  # has to correspond to the countries default SEPA paymentfile
+
+### List office
+
+    Twinfield::Request::Read.office
+
+## Known issues
+
+* The way configuration works may not work well in concurrent environments with multiple clients
+* The latest development and use in practice has been using the OAuth-based approach; the old Twinfield::Api::Session may not even work anymore

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/twinfield/abstract_model.rb

@@ -0,0 +1,7 @@
+module Twinfield
+  class AbstractModel
+    class << self
+      # private
+    end
+  end
+end

data/lib/twinfield/api/base_api.rb

@@ -0,0 +1,50 @@
+module Twinfield
+  module Api
+    class BaseApi
+      class << self
+        def session
+          @session ||= Twinfield.configuration.session_class.new
+          @session.logon
+          @session
+        end
+
+        def session= session
+          @client = nil
+          @session = session
+        end
+
+        def client
+          options = {
+            wsdl: wsdl,
+            env_namespace: :soap,
+            encoding: "UTF-8",
+            namespace_identifier: nil,
+            log: !!Twinfield.configuration.log_level,
+            log_level: Twinfield.configuration.log_level || :info
+          }
+          options[:logger] = Twinfield.configuration.logger if Twinfield.configuration.logger
+
+          @client ||= Savon.client(options)
+        end
+
+        def wsdl
+          raise "undefined .wsdl"
+        end
+
+        def cluster
+          session.cluster
+        end
+
+        def cluster_short_name
+          if cluster.match?("accounting2.")
+            "accounting2"
+          elsif cluster.match?("api.accounting")
+            "api.accounting"
+          else
+            "accounting"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twinfield/api/finder.rb

@@ -0,0 +1,45 @@
+module Twinfield
+  module Api
+    class Finder < BaseApi
+      class << self
+        def wsdl
+          Twinfield::WSDLS[cluster_short_name][:finder]
+        end
+
+        def actions
+          @actions ||= client.operations
+        end
+
+        # request
+        # see: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Transactions/SalesInvoices
+        def request(type, options = {})
+          Twinfield.configuration.logger&.debug("  ↳ #{caller.find { |a| !a.match(/\/gems\/|\/ruby\/|<internal:/) }}")
+
+          first_row = options.delete(:first_row) || 1
+          pattern = options.delete(:pattern) || "*"
+          max_rows = options.delete(:max_rows) || 100
+
+          message = {
+            "type" => type,
+            "pattern" => pattern,
+            "field" => "0",
+            "firstRow" => first_row,
+            "maxRows" => max_rows,
+            "options" => {
+              "ArrayOfString" => options.map { |k, v| {"string" => [k, v]} }
+            }
+          }
+
+          xml = client.operation(:search).build(attributes: {xmlns: "http://www.twinfield.com/"}, soap_header: session.header, message: message).build_document
+
+          client.call(:search, xml: strip_global_namespace_from_xml(xml))
+        end
+
+        def strip_global_namespace_from_xml xml
+          # ugly enough xmlns is prefixed even though it suggests an element in the global document's namespace
+          xml.gsub("<xmlns:", "<").gsub("</xmlns:", "</")
+        end
+      end
+    end
+  end
+end

data/lib/twinfield/api/o_auth_session.rb

@@ -0,0 +1,58 @@
+module Twinfield
+  module Api
+    class OAuthSession
+      HEADER_TEMPLATE = {
+        "Header" => {},
+        :attributes! => {
+          "Header" => {xmlns: "http://www.twinfield.com/"}
+        }
+      }
+
+      attr_accessor :cluster, :access_token
+
+      # sets up a new savon client which will be used for current Session
+      def initialize
+        @cluster = Twinfield.configuration.cluster
+        @access_token = Twinfield.configuration.access_token
+      end
+
+      # retrieve a session_id and cluster from twinfield
+      # relog is by default set to false so when logon is called on your
+      # current session, you wont lose your session_id
+      def logon(relog = false)
+        # no need to logon with OAuth
+      end
+
+      # call logon method with relog set to true
+      # this wil destroy the current session and cluster
+      def relog
+        logon(true)
+      end
+
+      # after a logon try you can ask the current status
+      def status
+        if connected?
+          "Ok"
+        else
+          "No access token"
+        end
+      end
+
+      # Returns true or false if current session has a session_id
+      # and cluster from twinfield
+      def connected?
+        !!@access_token && !!@cluster
+      end
+
+      def header
+        soap_header = HEADER_TEMPLATE
+
+        header_contents = {}
+        header_contents["AccessToken"] = access_token if access_token
+        header_contents["CompanyCode"] = Twinfield.configuration.company if Twinfield.configuration.company
+
+        soap_header.merge({"Header" => header_contents})
+      end
+    end
+  end
+end

data/lib/twinfield/api/process.rb

@@ -0,0 +1,44 @@
+module Twinfield
+  module Api
+    class Process < BaseApi
+      class << self
+        def wsdl
+          Twinfield::WSDLS[cluster_short_name][:process]
+        end
+
+        def actions
+          @actions ||= client.operations
+        end
+
+        def request(action = :process_xml_string, options = {}, &block)
+          Twinfield.configuration.logger&.debug("  ↳ #{caller.find { |a| !a.match(/\/gems\/|\/ruby\/|<internal:/) }}")
+
+          if actions.include?(action)
+            message = "<xmlRequest><![CDATA[#{block.call}]]></xmlRequest>"
+
+            client.call(action, attributes: {xmlns: "http://www.twinfield.com/"}, soap_header: session.header, message: message)
+          else
+            "action not found"
+          end
+        end
+
+        def read(element, options)
+          response = Twinfield::Api::Process.request(:process_xml_string) do
+            %(
+              <read>
+                <type>#{element}</type>
+                #{Twinfield::Api::Process.options_to_xml(options)}
+              </read>
+            )
+          end
+
+          Nokogiri::XML(response.body[:process_xml_string_response][:process_xml_string_result])
+        end
+
+        def options_to_xml(options)
+          options.map { |k, v| "<#{k}>#{v}</#{k}>" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/twinfield/api/session.rb

@@ -0,0 +1,170 @@
+module Twinfield
+  module Api
+    class Session
+      HEADER_TEMPLATE = {
+        "Header" => {},
+        :attributes! => {
+          "Header" => {xmlns: "http://www.twinfield.com/"}
+        }
+      }
+
+      attr_accessor :session_id, :cluster
+
+      # sets up a new savon client which will be used for current Session
+      def initialize
+        @client = Savon.client(wsdl: Twinfield::WSDLS[:session],
+          log: !!Twinfield.configuration.log_level,
+          log_level: Twinfield.configuration.log_level || :info)
+      end
+
+      # retrieve a session_id and cluster from twinfield
+      # relog is by default set to false so when logon is called on your
+      # current session, you wont lose your session_id
+      def logon(relog = false)
+        if connected? && (relog == false)
+          "already connected"
+        else
+          response = @client.call(:logon, message: Twinfield.configuration.to_logon_hash)
+
+          if response.body[:logon_response][:logon_result] == "Ok"
+            @session_id = response.header[:header][:session_id]
+            @cluster = response.body[:logon_response][:cluster]
+
+            select_company(Twinfield.configuration.company)
+          end
+
+          @message = response.body[:logon_response][:logon_result]
+        end
+      end
+
+      # call logon method with relog set to true
+      # this wil destroy the current session and cluster
+      def relog
+        logon(true)
+      end
+
+      # after a logon try you can ask the current status
+      def status
+        @message
+      end
+
+      # Returns true or false if current session has a session_id
+      # and cluster from twinfield
+      def connected?
+        !!@session_id && !!@cluster
+      end
+
+      # Abandons the session.
+      def abandon
+        if session_id
+          message = "<Abandon xmlns='http://www.twinfield.com/' />"
+          @client.call(:Abandon, attributes: {xmlns: "http://www.twinfield.com/"}, soap_header: header, message: message)
+
+          # TODO: Return real status
+          # There is no message from twinfield if the action succeeded
+          "Ok"
+        else
+          "no session found"
+        end
+      end
+
+      # Keep the session alive, to prevent session time out. A session time out will occur after 20 minutes.
+      def keep_alive
+        @client.request :keep_alive do
+          soap.header = header
+          soap.body = "<KeepAliveResponse xmlns='http://www.twinfield.com/' />"
+        end
+        # TODO: Return real status
+        # There is no message from twinfield if the action succeeded
+        "Ok"
+      end
+
+      def header
+        soap_header = HEADER_TEMPLATE
+        soap_header = soap_header.merge({"Header" => {"SessionID" => session_id}}) if session_id
+        soap_header
+      end
+
+      # Gets the session's user role.
+      def get_role
+        # <?xml version="1.0" encoding="utf-8"?>
+        # <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+        #   <soap:Header>
+        #     <Header xmlns="http://www.twinfield.com/">
+        #       <SessionID>string</SessionID>
+        #     </Header>
+        #   </soap:Header>
+        #   <soap:Body>
+        #     <GetRole xmlns="http://www.twinfield.com/" />
+        #   </soap:Body>
+        # </soap:Envelope>
+        raise NotImplementedError
+      end
+
+      # Sends the sms code.
+      def sms_send_code
+        # <?xml version="1.0" encoding="utf-8"?>
+        # <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+        #   <soap:Header>
+        #     <Header xmlns="http://www.twinfield.com/">
+        #       <SessionID>string</SessionID>
+        #     </Header>
+        #   </soap:Header>
+        #   <soap:Body>
+        #     <SmsSendCode xmlns="http://www.twinfield.com/" />
+        #   </soap:Body>
+        # </soap:Envelope>
+        raise NotImplementedError
+      end
+
+      # Logs on with the sms code.
+      def sms_logon
+        # <?xml version="1.0" encoding="utf-8"?>
+        # <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+        #   <soap:Header>
+        #     <Header xmlns="http://www.twinfield.com/">
+        #       <SessionID>string</SessionID>
+        #     </Header>
+        #   </soap:Header>
+        #   <soap:Body>
+        #     <SmsLogon xmlns="http://www.twinfield.com/">
+        #       <smsCode>string</smsCode>
+        #     </SmsLogon>
+        #   </soap:Body>
+        # </soap:Envelope>
+        raise NotImplementedError
+      end
+
+      # Changes the password.
+      def change_password
+        # <?xml version="1.0" encoding="utf-8"?>
+        # <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+        #   <soap:Header>
+        #     <Header xmlns="http://www.twinfield.com/">
+        #       <SessionID>string</SessionID>
+        #     </Header>
+        #   </soap:Header>
+        #   <soap:Body>
+        #     <ChangePassword xmlns="http://www.twinfield.com/">
+        #       <currentPassword>string</currentPassword>
+        #       <newPassword>string</newPassword>
+        #     </ChangePassword>
+        #   </soap:Body>
+        # </soap:Envelope>
+        raise NotImplementedError
+      end
+
+      # Selects a company.
+      def select_company(code)
+        message = "<company>#{code}</company>"
+
+        Savon.client(wsdl: "#{@cluster}/webservices/session.asmx?wsdl",
+          env_namespace: :soap,
+          encoding: "UTF-8",
+          namespace_identifier: nil).call(:select_company, attributes: {xmlns: "http://www.twinfield.com/"}, soap_header: header, message: message)
+
+        "Ok"
+      end
+    end
+  end
+end