zipdatev 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b14ed5e1f68c6aae3b564a967bc36dd5ff0d4fdec083d682452161ceb565bcd
+  data.tar.gz: 6c98b7e93719825e69ef0c0483134a256c864fbb734978cc5102f4b7272b82fe
+SHA512:
+  metadata.gz: ff15c712b6e8661f54f28b5ac32f9d575e160d5973e8c43dd2330bebe174c1b430457ad20f6d8695e39c79299f87f6937cfcc81142416cc07ac09105ea443ea2
+  data.tar.gz: 8b9ff68c49b67c4059797ccc73bd68bc66a28299cafae8ad8b5b18a16f9634f85ee2b404cf5c58bade0ab42df38d2ef1314513dd7e34169f4320bb4a650d2126

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dexter Technologies GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/zipdatev/constants.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+
+module ZipDatev
+  # Constants for DATEV validation including ISO codes and validation patterns.
+  #
+  # Currency codes are from ISO 4217, country codes from ISO 3166,
+  # both as specified in the DATEV XSD schemas.
+  module Constants
+    # ISO 4217 currency codes supported by DATEV
+    # Extracted from Belegverwaltung_online_ledger_types_v060.xsd (p1 type)
+    CURRENCY_CODES = %w[
+      AED AFA AFN ALL AMD ANG AOA AON AOR ARS ATS AUD AWG AZM AZN
+      BAM BBD BDT BEF BGL BGN BHD BIF BMD BND BOB BRL BSD BTN BWP BYB BYN BYR BZD
+      CAD CDF CHF CLP CMG CNH CNY COP CRC CSD CUP CVE CYP CZK
+      DEM DJF DJV DKK DOP DZD
+      ECS EEK EGP ERN ESP ETB EUR
+      FIM FJD FKP FRF
+      GBP GEL GHC GHS GIP GMD GNF GRD GTQ GWP GYD
+      HKD HNL HRK HTG HUF
+      IDR IEP ILS INR IQD IRR ISK ITL
+      JMD JOD JPY
+      KES KGS KHR KMF KPW KRW KWD KYD KZT
+      LAK LBP LKR LRD LSL LTL LUF LVL LYD
+      MAD MDL MGA MGF MKD MMK MNT MOP MRO MRU MTL MUR MVR MWK MXN MYR MZM MZN
+      NAD NGN NIO NLG NOK NPR NZD
+      OMR
+      PAB PEN PGK PHP PKR PLN PLZ PTE PYG
+      QAR
+      ROL RON RSD RUB RUR RWF
+      SAR SBD SCR SDD SDG SEK SGD SHP SIT SKK SLL SOS SRD SRG SSP STD SVC SYP SZL
+      THB TJR TJS TMM TMT TND TOP TRL TRY TTD TWD TZS
+      UAH UGX USD UYU UZS
+      VEB VEF VES VND VUV
+      WST
+      XAF XCD XEU XOF XPF
+      YER YUM
+      ZAR ZMK ZMW ZRN ZWD ZWR
+    ].freeze
+
+    # ISO 3166 two-letter country codes supported by DATEV
+    # Extracted from Belegverwaltung_online_ledger_types_v060.xsd (p10014 type)
+    COUNTRY_CODES = %w[
+      AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ
+      BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ
+      CA CC CD CF CG CH CI CK CL CM CN CO CR CS CU CV CW CX CY CZ
+      DE DJ DK DM DO DZ
+      EC EE EG EH ER ES ET
+      FI FJ FK FM FO FR
+      GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY
+      HK HM HN HR HT HU
+      ID IE IL IM IN IO IQ IR IS IT
+      JE JM JO JP
+      KE KG KH KI KM KN KP KR KW KY KZ
+      LA LB LC LI LK LR LS LT LU LV LY
+      MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ
+      NA NC NE NF NG NI NL NO NP NR NU NZ
+      OM
+      PA PE PF PG PH PK PL PM PN PR PS PT PW PY
+      QA
+      RE RO RS RU RW
+      SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ
+      TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ
+      UA UG UM US UY UZ
+      VA VC VE VG VI VN VU
+      WF WS
+      XI XK
+      YE YT
+      ZA ZM ZW
+    ].freeze
+
+    # Pattern for invoice ID: alphanumeric + $%&*+-/
+    # From XSD p10040: [a-zA-Z0-9$%&*+-/]{0,36}
+    INVOICE_ID_PATTERN = %r{\A[a-zA-Z0-9$%&*+\-/]{0,36}\z}
+
+    # Pattern for internal invoice ID: alphanumeric + $%&*+-/
+    # From XSD p10: [a-zA-Z0-9$%&*+-/]{1,12}
+    INTERNAL_INVOICE_ID_PATTERN = %r{\A[a-zA-Z0-9$%&*+\-/]{1,12}\z}
+
+    # Pattern for order ID: alphanumeric + $%&*+-./ (includes dot)
+    # From XSD p13: [a-zA-Z0-9$%&*+-.\/]{1,30}
+    ORDER_ID_PATTERN = %r{\A[a-zA-Z0-9$%&*+\-./]{1,30}\z}
+
+    # Pattern for IBAN: 2 uppercase letters + 2 digits + 11-30 alphanumeric
+    # From XSD p10010: [A-Z]{2}\d\d([A-Za-z0-9]){11,30}
+    IBAN_PATTERN = /\A[A-Z]{2}\d{2}[A-Za-z0-9]{11,30}\z/
+
+    # Pattern for SWIFT/BIC: 4 uppercase + 2 uppercase + 2 alphanumeric + 0-3 alphanumeric
+    # From XSD p10030: [A-Z]{4}[A-Z]{2}([A-Z0-9]){2}([A-Z0-9]){0,3}
+    SWIFT_PATTERN = /\A[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{0,3}\z/
+
+    # Pattern for VAT ID: alphanumeric + space, dot, underscore
+    # From XSD p10027: [0-9a-zA-Z. _]{1,15}
+    VAT_ID_PATTERN = /\A[0-9a-zA-Z. _]{1,15}\z/
+
+    # DATEV date range
+    # From XSD p10029: 1753-01-01 to 9999-12-31
+    MIN_DATE = Date.new(1753, 1, 1)
+    MAX_DATE = Date.new(9999, 12, 31)
+
+    # Amount constraints
+    # From XSD p7: 12 total digits, 2 fraction digits
+    MIN_AMOUNT = BigDecimal("-9999999999.99")
+    MAX_AMOUNT = BigDecimal("9999999999.99")
+
+    # Tax percentage constraints
+    # From XSD p33: 0.00 to 99.99
+    MIN_TAX = BigDecimal("0.00")
+    MAX_TAX = BigDecimal("99.99")
+
+    # Exchange rate constraints
+    # From XSD p31: 0.000001 to 9999.999999
+    MIN_EXCHANGE_RATE = BigDecimal("0.000001")
+    MAX_EXCHANGE_RATE = BigDecimal("9999.999999")
+
+    # Discount amount constraints
+    # From XSD p34: 0.01 to 99999999.99
+    MIN_DISCOUNT_AMOUNT = BigDecimal("0.01")
+    MAX_DISCOUNT_AMOUNT = BigDecimal("99999999.99")
+
+    # Payment conditions ID range
+    # From XSD p23: 9 to 999
+    MIN_PAYMENT_CONDITIONS_ID = 9
+    MAX_PAYMENT_CONDITIONS_ID = 999
+
+    # Account number constraints
+    # From XSD p10039: 1 to 999999999
+    MIN_ACCOUNT_NO = 1
+    MAX_ACCOUNT_NO = 999_999_999
+
+    # Business partner account number constraints
+    # From XSD p11: 10000 to 999999999
+    MIN_BP_ACCOUNT_NO = 10_000
+    MAX_BP_ACCOUNT_NO = 999_999_999
+
+    # BU code constraints
+    # From XSD p10033: 0 to 9999
+    MIN_BU_CODE = 0
+    MAX_BU_CODE = 9999
+
+    # String length constraints
+    INVOICE_ID_MAX_LENGTH = 36
+    INTERNAL_INVOICE_ID_MAX_LENGTH = 12
+    ORDER_ID_MAX_LENGTH = 30
+    BOOKING_TEXT_MAX_LENGTH = 60
+    INFORMATION_MAX_LENGTH = 120
+    SUPPLIER_NAME_MAX_LENGTH = 50
+    SUPPLIER_CITY_MAX_LENGTH = 30
+    ACCOUNT_NAME_MAX_LENGTH = 40
+    PARTY_ID_MAX_LENGTH = 15
+    VAT_ID_MAX_LENGTH = 15
+    IBAN_MAX_LENGTH = 34
+    SWIFT_MAX_LENGTH = 11
+    BANK_CODE_MAX_LENGTH = 10
+    BANK_ACCOUNT_MAX_LENGTH = 30
+    COST_CATEGORY_ID_MAX_LENGTH = 36
+  end
+end

data/lib/zipdatev/document.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module ZipDatev
+  # Represents a document entry in the DATEV package.
+  #
+  # A document bundles an invoice with its associated attachment files
+  # and metadata (invoice month, folder name). Each document becomes
+  # a <document> element in the generated document.xml.
+  #
+  # @example Creating a document with an invoice and PDF attachment
+  #   document = ZipDatev::Document.new(
+  #     invoice: invoice,
+  #     attachments: ["/path/to/invoice.pdf"],
+  #     invoice_month: "2023-01",
+  #     folder_name: "Eingangsrechnungen"
+  #   )
+  class Document
+    include ActiveModel::Model
+    include ActiveModel::Validations
+
+    attr_accessor :invoice, :attachments, :invoice_month, :folder_name, :repository
+
+    # Validations
+    validates :invoice, presence: true
+    validate :invoice_must_be_valid
+    validate :attachments_must_exist
+
+    def initialize(invoice: nil, attachments: [], invoice_month: nil, folder_name: nil, repository: nil)
+      @invoice = invoice
+      @attachments = attachments || []
+      @invoice_month = invoice_month
+      @folder_name = folder_name
+      @repository = repository
+    end
+
+    private
+
+    def invoice_must_be_valid
+      return if invoice.blank?
+      return if invoice.valid?
+
+      invoice.errors.each do |error|
+        errors.add(:invoice, "#{error.attribute} #{error.message}")
+      end
+    end
+
+    def attachments_must_exist
+      return if attachments.blank?
+
+      attachments.each do |path|
+        next if path.nil?
+        next if File.exist?(path)
+
+        errors.add(:attachments, "file not found: #{path}")
+      end
+    end
+  end
+end

data/lib/zipdatev/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ZipDatev
+  # Base error class for all ZipDatev errors
+  class Error < StandardError; end
+
+  # Raised when validation fails on models (Invoice, LineItem, Document)
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: [])
+      @errors = errors
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      return "Validation failed" if errors.empty?
+
+      "Validation failed: #{errors.join(", ")}"
+    end
+  end
+
+  # Raised when package creation fails
+  class PackageError < Error; end
+
+  # Raised when XSD schema validation fails
+  class SchemaValidationError < Error
+    attr_reader :schema_errors
+
+    def initialize(message = nil, schema_errors: [])
+      @schema_errors = schema_errors
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      return "Schema validation failed" if schema_errors.empty?
+
+      "Schema validation failed: #{schema_errors.join(", ")}"
+    end
+  end
+end

data/lib/zipdatev/generators/base.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "active_support/core_ext/string/inflections"
+
+module ZipDatev
+  module Generators
+    # Base class for XML generators with shared helper methods.
+    #
+    # Provides utilities for formatting dates, decimals, and converting
+    # Ruby naming conventions to DATEV XML naming conventions.
+    class Base
+      # DATEV fixed values
+      VERSION = "6.0"
+      XML_DATA = "Kopie nur zur Verbuchung berechtigt nicht zum Vorsteuerabzug"
+
+      # Document XML namespaces
+      DOCUMENT_XMLNS = "http://xml.datev.de/bedi/tps/document/v06.0"
+      DOCUMENT_XSI_SCHEMA_LOCATION = "http://xml.datev.de/bedi/tps/document/v06.0 Document_v060.xsd"
+
+      # Ledger XML namespaces
+      LEDGER_XMLNS = "http://xml.datev.de/bedi/tps/ledger/v060"
+      LEDGER_XSI_SCHEMA_LOCATION =
+        "http://xml.datev.de/bedi/tps/ledger/v060 Belegverwaltung_online_ledger_import_v060.xsd"
+
+      # XSI namespace (shared)
+      XSI_XMLNS = "http://www.w3.org/2001/XMLSchema-instance"
+
+      # Element order for accountsPayableLedger (must match XSD sequence)
+      ACCOUNTS_PAYABLE_LEDGER_ELEMENTS = %i[
+        date amount discount_amount account_no bu_code cost_amount
+        cost_category_id cost_category_id2 tax information
+        currency_code invoice_id booking_text type_of_receivable
+        own_vat_id ship_from_country party_id paid_at internal_invoice_id
+        vat_id ship_to_country exchange_rate bank_code bank_account
+        bank_country iban swift_code account_name payment_conditions_id
+        payment_order discount_percentage discount_payment_date
+        discount_amount_2 discount_percentage_2 discount_payment_date_2
+        due_date bp_account_no delivery_date order_id
+        supplier_name supplier_city
+      ].freeze
+
+      # Fields that should be formatted as decimals with 2 decimal places
+      DECIMAL_FIELDS = %i[
+        amount discount_amount cost_amount tax discount_percentage
+        discount_amount_2 discount_percentage_2
+      ].freeze
+
+      # Fields that should be formatted as decimals with 6 decimal places
+      EXCHANGE_RATE_FIELDS = %i[exchange_rate].freeze
+
+      # Fields that are dates
+      DATE_FIELDS = %i[
+        date paid_at discount_payment_date discount_payment_date_2
+        due_date delivery_date
+      ].freeze
+
+      # Fields that are booleans
+      BOOLEAN_FIELDS = %i[payment_order].freeze
+
+      private
+
+      # Format a date for XML output (YYYY-MM-DD)
+      #
+      # @param date [Date, nil] The date to format
+      # @return [String, nil] Formatted date string or nil if date is nil
+      def format_date(date)
+        return nil if date.nil?
+
+        date.strftime("%Y-%m-%d")
+      end
+
+      # Format a datetime for XML output (YYYY-MM-DDTHH:MM:SS)
+      #
+      # @param datetime [DateTime, Time, nil] The datetime to format
+      # @return [String, nil] Formatted datetime string or nil if datetime is nil
+      def format_datetime(datetime)
+        return nil if datetime.nil?
+
+        datetime.strftime("%Y-%m-%dT%H:%M:%S")
+      end
+
+      # Format a decimal value for XML output with specified precision
+      #
+      # @param value [BigDecimal, Numeric, nil] The value to format
+      # @param precision [Integer] Number of decimal places (default: 2)
+      # @return [String, nil] Formatted decimal string or nil if value is nil
+      def format_decimal(value, precision: 2)
+        return nil if value.nil?
+
+        format("%.#{precision}f", value)
+      end
+
+      # Convert a Ruby snake_case symbol to XML camelCase element name
+      #
+      # @param ruby_name [Symbol, String] The Ruby attribute name
+      # @return [String] The XML element name in camelCase
+      def to_xml_name(ruby_name)
+        # Handle special cases
+        name = ruby_name.to_s
+        case name
+        when "cost_category_id2"
+          "costCategoryId2"
+        when "discount_amount_2"
+          "discountAmount2"
+        when "discount_percentage_2"
+          "discountPercentage2"
+        when "discount_payment_date_2"
+          "discountPaymentDate2"
+        else
+          name.camelize(:lower)
+        end
+      end
+
+      # Format a field value for XML based on its type
+      #
+      # @param field [Symbol] The field name
+      # @param value [Object] The field value
+      # @return [String, nil] Formatted value for XML output
+      def format_field_value(field, value)
+        return nil if value.nil?
+
+        if DATE_FIELDS.include?(field)
+          format_date(value)
+        elsif DECIMAL_FIELDS.include?(field)
+          format_decimal(value, precision: 2)
+        elsif EXCHANGE_RATE_FIELDS.include?(field)
+          format_decimal(value, precision: 6)
+        elsif BOOLEAN_FIELDS.include?(field)
+          value ? "true" : "false"
+        else
+          value.to_s
+        end
+      end
+
+      # Generate a safe ASCII filename from an invoice ID
+      #
+      # @param invoice_id [String] The invoice ID
+      # @return [String] ASCII-safe filename for the ledger XML
+      def ledger_filename(invoice_id)
+        safe_id = invoice_id.to_s.parameterize(preserve_case: true)
+        "Rechnungsdaten_RE_#{safe_id}.xml"
+      end
+    end
+  end
+end

data/lib/zipdatev/generators/document_xml.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ZipDatev
+  module Generators
+    # Generates the DATEV document.xml administrative file.
+    #
+    # The document.xml file is the manifest that lists all invoices and
+    # attachments in the package. It contains references to ledger XML files
+    # and optional PDF/image attachments.
+    #
+    # @example Generate document.xml for a package
+    #   generator = ZipDatev::Generators::DocumentXml.new(
+    #     package: package,
+    #     created_at: Time.now
+    #   )
+    #   xml_doc = generator.generate
+    class DocumentXml < Base
+      # Default folder name for accounts payable ledger
+      DEFAULT_FOLDER_NAME = "Eingangsrechnungen"
+
+      # @return [Package] The package to generate document.xml for
+      attr_reader :package
+
+      # @return [Time] The creation timestamp
+      attr_reader :created_at
+
+      # Initialize a new document XML generator.
+      #
+      # @param package [Package] The package to generate document.xml for
+      # @param created_at [Time] The creation timestamp (default: current time)
+      def initialize(package:, created_at: nil)
+        super()
+        @package = package
+        @created_at = created_at || Time.now
+      end
+
+      # Generate the document.xml document.
+      #
+      # @return [Nokogiri::XML::Document] The generated XML document
+      def generate
+        Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+          xml.archive(archive_attributes) do
+            generate_header(xml)
+            generate_content(xml)
+          end
+        end.doc
+      end
+
+      private
+
+      # Attributes for the archive root element
+      def archive_attributes
+        {
+          "xmlns" => DOCUMENT_XMLNS,
+          "xmlns:xsi" => XSI_XMLNS,
+          "xsi:schemaLocation" => DOCUMENT_XSI_SCHEMA_LOCATION,
+          "version" => Base::VERSION,
+          "generatingSystem" => package.generating_system
+        }
+      end
+
+      # Generate the header element
+      def generate_header(xml)
+        xml.header do
+          xml.date format_datetime(created_at)
+        end
+      end
+
+      # Generate the content element with all documents
+      def generate_content(xml)
+        xml.content do
+          package.documents.each do |document|
+            generate_document(xml, document)
+          end
+        end
+      end
+
+      # Generate a document element for a single document
+      def generate_document(xml, document)
+        xml.document do
+          # Generate ledger extension (accountsPayableLedger)
+          generate_ledger_extension(xml, document)
+
+          # Generate file extensions for attachments
+          document.attachments.each do |attachment_path|
+            generate_file_extension(xml, attachment_path)
+          end
+
+          # Generate optional repository structure
+          generate_repository(xml, document) if document.repository
+        end
+      end
+
+      # Generate the accountsPayableLedger extension element
+      def generate_ledger_extension(xml, document)
+        datafile = ledger_filename(
+          document.invoice.consolidated_invoice_id || document.invoice.invoice_id
+        )
+
+        xml.extension("xsi:type" => "accountsPayableLedger", "datafile" => datafile) do
+          # Property key 1: Invoice month (YYYY-MM format)
+          # Use provided value or derive from invoice date
+          invoice_month = document.invoice_month || derive_invoice_month(document.invoice)
+          xml.property("value" => invoice_month, "key" => "1")
+
+          # Property key 3: Folder name
+          # Use provided value or default to "Eingangsrechnungen"
+          folder_name = document.folder_name || DEFAULT_FOLDER_NAME
+          xml.property("value" => folder_name, "key" => "3")
+        end
+      end
+
+      # Derive invoice month from invoice date in YYYY-MM format
+      #
+      # @param invoice [Invoice] The invoice
+      # @return [String] The invoice month in YYYY-MM format
+      def derive_invoice_month(invoice)
+        date = invoice.consolidated_date || invoice.date
+        return Time.now.strftime("%Y-%m") unless date
+
+        date.strftime("%Y-%m")
+      end
+
+      # Generate a File extension element for an attachment
+      def generate_file_extension(xml, attachment_path)
+        filename = File.basename(attachment_path)
+        xml.extension("xsi:type" => "File", "name" => filename)
+      end
+
+      # Generate the repository element for filing structure
+      def generate_repository(xml, document)
+        repo = document.repository
+        xml.repository do
+          xml.level("id" => "1", "name" => repo.level1) if repo.level1
+          xml.level("id" => "2", "name" => repo.level2) if repo.level2
+          xml.level("id" => "3", "name" => repo.level3) if repo.level3
+        end
+      end
+    end
+  end
+end