invoicing 0.1.0

data/lib/invoicing/ledger_item/render_ubl.rb

@@ -0,0 +1,268 @@
+require 'builder'
+
+module Invoicing
+  module LedgerItem
+    # Included into ActiveRecord model object when +acts_as_ledger_item+ is invoked.
+    module RenderUBL
+      
+      # Renders this invoice or credit note into a complete XML document conforming to the
+      # {OASIS Universal Business Language}[http://ubl.xml.org/] (UBL) open standard for interchange
+      # of business documents ({specification}[http://www.oasis-open.org/committees/ubl/]). This
+      # format, albeit a bit verbose, is increasingly being adopted as an international standard. It
+      # can represent some very complicated multi-currency, multi-party business relationships, but
+      # is still quite usable for simple cases.
+      #
+      # It is recommended that you present machine-readable UBL data in your application in the
+      # same way as you present human-readable invoices in HTML. For example, in a Rails controller,
+      # you could use:
+      #
+      #   class AccountsController < ApplicationController
+      #     def show
+      #       @ledger_item = LedgerItem.find(params[:id])
+      #       # ... check whether current user has access to this document ...
+      #       respond_to do |format|
+      #         format.html # show.html.erb
+      #         format.xml  { render :xml => @ledger_item.render_ubl }
+      #       end
+      #     end
+      #   end
+      def render_ubl(options={})
+        UBLOutputBuilder.new(self, options).build
+      end
+      
+      
+      class UBLOutputBuilder #:nodoc:
+        # XML Namespaces required by UBL
+        UBL_NAMESPACES = {
+          "xmlns:cac" => "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
+          "xmlns:cbc" => "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
+        }
+        
+        UBL_DOC_NAMESPACES = {
+          :Invoice              => "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
+          :SelfBilledInvoice    => "urn:oasis:names:specification:ubl:schema:xsd:SelfBilledInvoice-2",
+          :CreditNote           => "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2",
+          :SelfBilledCreditNote => "urn:oasis:names:specification:ubl:schema:xsd:SelfBilledCreditNote-2"
+        }
+        
+        attr_reader :ledger_item, :options, :cached_values, :doc_type, :factor
+        
+        def initialize(ledger_item, options)
+          @ledger_item = ledger_item
+          @options = options
+          @cached_values = {}
+          subtype = ledger_item.send(:ledger_item_class_info).subtype
+          @doc_type = 
+            if [:invoice, :credit_note].include? subtype
+              if total_amount >= BigDecimal('0')
+                @factor = BigDecimal('1')
+                sender_details[:is_self] ? :Invoice : :SelfBilledInvoice
+              else
+                @factor = BigDecimal('-1')
+                sender_details[:is_self] ? :CreditNote : :SelfBilledCreditNote
+              end
+            else
+              raise RuntimeError, "render_ubl not implemented for ledger item subtype #{subtype.inspect}"
+            end
+        end
+        
+        # For convenience while building the XML structure, method_missing redirects method calls
+        # to the ledger item (taking account of method renaming via acts_as_ledger_item options);
+        # calls to foo_of(line_item) are redirected to line_item.foo (taking account of method
+        # renaming via acts_as_line_item options).
+        def method_missing(method_id, *args, &block)
+          method_id = method_id.to_sym
+          if method_id.to_s =~ /^(.*)_of$/
+            method_id = $1.to_sym
+            line_item = args[0]
+            line_item.send(:line_item_class_info).get(line_item, method_id)
+          else
+            cached_values[method_id] ||= ledger_item.send(:ledger_item_class_info).get(ledger_item, method_id)
+          end
+        end
+        
+        # Returns a UBL XML rendering of the ledger item previously passed to the constructor.
+        def build
+          ubl = Builder::XmlMarkup.new :indent => 4
+          ubl.instruct! :xml
+          
+          ubl.ubl doc_type, UBL_NAMESPACES.clone.update({'xmlns:ubl' => UBL_DOC_NAMESPACES[doc_type]}) do |invoice|
+            invoice.cbc :ID, identifier
+            invoice.cbc :UUID, uuid if uuid
+            
+            issue_date_formatted, issue_time_formatted = (issue_date || Time.now).in_time_zone.xmlschema.split('T')
+            invoice.cbc :IssueDate, issue_date_formatted
+            invoice.cbc :IssueTime, issue_time_formatted
+            
+            # Different document types have the child elements InvoiceTypeCode, Note and
+            # TaxPointDate in a different order. WTF?!
+            if doc_type == :Invoice
+              invoice.cbc :InvoiceTypeCode, method_missing(:type)
+              invoice.cbc :Note, description
+              invoice.cbc :TaxPointDate, issue_date_formatted
+            else
+              invoice.cbc :TaxPointDate, issue_date_formatted
+              invoice.cbc :InvoiceTypeCode, method_missing(:type) if doc_type == :SelfBilledInvoice
+              invoice.cbc :Note, description
+            end
+            
+            invoice.cac :InvoicePeriod do |invoice_period|
+              build_period(invoice_period, period_start, period_end)
+            end if period_start && period_end
+            
+            if [:Invoice, :CreditNote].include?(doc_type)
+            
+              invoice.cac :AccountingSupplierParty do |supplier|
+                build_party supplier, sender_details
+              end
+              invoice.cac :AccountingCustomerParty do |customer|
+                customer.cbc :SupplierAssignedAccountID, recipient_id
+                build_party customer, recipient_details
+              end
+              
+            elsif [:SelfBilledInvoice, :SelfBilledCreditNote].include?(doc_type)
+            
+              invoice.cac :AccountingCustomerParty do |customer|
+                build_party customer, recipient_details
+              end
+              invoice.cac :AccountingSupplierParty do |supplier|
+                supplier.cbc :CustomerAssignedAccountID, sender_id
+                build_party supplier, sender_details
+              end
+              
+            end
+            
+            invoice.cac :PaymentTerms do |payment_terms|
+              payment_terms.cac :SettlementPeriod do |settlement_period|
+                build_period(settlement_period, issue_date || Time.now, due_date)
+              end
+            end if due_date && [:Invoice, :SelfBilledInvoice].include?(doc_type)
+            
+            invoice.cac :TaxTotal do |tax_total|
+              tax_total.cbc :TaxAmount, (factor*tax_amount).to_s, :currencyID => currency
+            end if tax_amount
+            
+            invoice.cac :LegalMonetaryTotal do |monetary_total|
+              monetary_total.cbc :TaxExclusiveAmount, (factor*(total_amount - tax_amount)).to_s,
+                :currencyID => currency if tax_amount
+              monetary_total.cbc :PayableAmount, (factor*total_amount).to_s, :currencyID => currency
+            end
+            
+            line_items.sorted(:tax_point).each do |line_item|
+              line_tag = if [:CreditNote, :SelfBilledCreditNote].include? doc_type
+                :CreditNoteLine
+              else
+                :InvoiceLine
+              end
+              
+              invoice.cac line_tag do |invoice_line|
+                build_line_item(invoice_line, line_item)
+              end
+            end
+          end
+          ubl.target!
+        end
+        
+        
+        # Given a <tt>Builder::XmlMarkup</tt> instance and two datetime objects, builds a UBL
+        # representation of the period between the two dates and times, something like the
+        # following:
+        #
+        #   <cbc:StartDate>2008-05-06</cbc:StartTime>
+        #   <cbc:StartTime>12:34:56+02:00</cbc:StartTime>
+        #   <cbc:EndDate>2008-07-02</cbc:EndDate>
+        #   <cbc:EndTime>01:02:03+02:00</cbc:EndTime>
+        def build_period(xml, start_datetime, end_datetime)
+          start_date, start_time = start_datetime.in_time_zone.xmlschema.split('T')
+          end_date, end_time = end_datetime.in_time_zone.xmlschema.split('T')
+          xml.cbc :StartDate, start_date
+          xml.cbc :StartTime, start_time
+          xml.cbc :EndDate, end_date
+          xml.cbc :EndTime, end_time
+        end
+        
+        
+        # Given a <tt>Builder::XmlMarkup</tt> instance and a supplier/customer details hash (as
+        # returned by <tt>LedgerItem#sender_details</tt> and <tt>LedgerItem#recipient_details</tt>,
+        # builds a UBL representation of that party, something like the following:
+        #
+        #   <cac:Party>
+        #       <cac:PartyName>
+        #           <cbc:Name>The Big Bank</cbc:Name>
+        #       </cac:PartyName>
+        #       <cac:PostalAddress>
+        #           <cbc:StreetName>Paved With Gold Street</cbc:StreetName>
+        #           <cbc:CityName>London</cbc:CityName>
+        #           <cbc:PostalZone>E14 5HQ</cbc:PostalZone>
+        #           <cac:Country><cbc:IdentificationCode>GB</cbc:IdentificationCode></cac:Country>
+        #       </cac:PostalAddress>
+        #   </cac:Party>
+        def build_party(xml, details)
+          xml.cac :Party do |party|
+            party.cac :PartyName do |party_name|
+              party_name.cbc :Name, details[:name]
+            end if details[:name]
+            
+            party.cac :PostalAddress do |postal_address|
+              street1, street2 = details[:address].strip.split("\n", 2)
+              postal_address.cbc :StreetName,           street1               if street1
+              postal_address.cbc :AdditionalStreetName, street2               if street2
+              postal_address.cbc :CityName,             details[:city]        if details[:city]
+              postal_address.cbc :PostalZone,           details[:postal_code] if details[:postal_code]
+              postal_address.cbc :CountrySubentity,     details[:state]       if details[:state]
+              postal_address.cac :Country do |country|
+                country.cbc :IdentificationCode, details[:country_code] if details[:country_code]
+                country.cbc :Name,               details[:country]      if details[:country]
+              end if details[:country_code] || details[:country]
+            end
+            
+            party.cac :PartyTaxScheme do |party_tax_scheme|
+              party_tax_scheme.cbc :CompanyID, details[:tax_number]
+              party_tax_scheme.cac :TaxScheme do |tax_scheme|
+                tax_scheme.cbc :ID, "VAT" # TODO: make country-dependent (e.g. GST in Australia)
+              end
+            end if details[:tax_number]
+            
+            party.cac :Contact do |contact|
+              contact.cbc :Name, details[:contact_name]
+            end if details[:contact_name]
+          end
+        end
+        
+        
+        # Given a <tt>Builder::XmlMarkup</tt> instance and a +LineItem+ instance, builds a UBL
+        # representation of that line item, something like the following:
+        #
+        #   <cbc:ID>123</cbc:ID>
+        #   <cbc:UUID>0cc659f0-cfac-012b-481d-0017f22d32c0</cbc:UUID>
+        #   <cbc:InvoicedQuantity>1</cbc:InvoicedQuantity>
+        #   <cbc:LineExtensionAmount currencyID="GBP">123.45</cbc:LineExtensionAmount>
+        #   <cbc:TaxPointDate>2009-01-01</cbc:TaxPointDate>
+        #   <cac:TaxTotal><cbc:TaxAmount currencyID="GBP">12.34</cbc:TaxAmount></cac:TaxTotal>
+        #   <cac:Item><cbc:Description>Foo bar baz</cbc:Description></cac:Item>
+        def build_line_item(invoice_line, line_item)
+          invoice_line.cbc :ID, id_of(line_item)
+          invoice_line.cbc :UUID, uuid_of(line_item) if uuid_of(line_item)
+          quantity_tag = [:Invoice, :SelfBilledInvoice].include?(doc_type) ? :InvoicedQuantity : :CreditedQuantity
+          invoice_line.cbc quantity_tag, quantity_of(line_item) if quantity_of(line_item)
+          invoice_line.cbc :LineExtensionAmount, (factor*net_amount_of(line_item)).to_s, :currencyID => currency
+          invoice_line.cbc :TaxPointDate, tax_point_of(line_item).in_time_zone.strftime('%Y-%m-%d') if tax_point_of(line_item)
+          
+          invoice_line.cac :TaxTotal do |tax_total|
+            tax_total.cbc :TaxAmount, (factor*tax_amount_of(line_item)).to_s, :currencyID => currency
+          end if tax_amount_of(line_item)
+          
+          invoice_line.cac :Item do |item|
+            item.cbc :Description, description_of(line_item)
+            #cac:BuyersItemIdentification
+            #cac:SellersItemIdentification
+            #cac:ClassifiedTaxCategory
+            #cac:ItemInstance
+          end
+            
+          #cac:Price
+        end
+      end
+    end
+  end
+end

data/lib/invoicing/line_item.rb

@@ -0,0 +1,246 @@
+module Invoicing
+  # = Line item objects
+  #
+  # A line item is a single charge on an invoice or credit note, for example representing the sale
+  # of one particular product. An invoice or credit note with a non-zero +total_amount+ must have at
+  # least one +LineItem+ object associated with it, and its +total_amount+ must equal the sum of the
+  # +net_amount+ and +tax_amount+ values of all +LineItem+ objects associated with it. For details
+  # on invoices and credit notes, see the +LedgerItem+ module.
+  #
+  # Many of the important principles set down in the +LedgerItem+ module also apply for line items;
+  # for example, once you have created a line item you generally shouldn't change it again. If you
+  # need to correct a mistake, create an additional line item of the same type but a negative value.
+  #
+  # == Using +LineItem+
+  #
+  # In all likelihood you will have different types of charges which you need to make to your customers.
+  # We store all those different types of line item in the same database table and use ActiveRecord's
+  # single table inheritance to build a class hierarchy. You must create at least one line item
+  # model class in your application, like this:
+  #
+  #   class LineItem < ActiveRecord::Base
+  #     acts_as_line_item
+  #     belongs_to :ledger_item
+  #   end
+  #
+  # You may then create a class hierarchy to suit your needs, for example:
+  #
+  #   class ProductSale < LineItem
+  #     belongs_to :product
+  #     
+  #     def description
+  #       product.title
+  #     end
+  #   end
+  #   
+  #   class ShippingCharges < LineItem
+  #     def description
+  #       "Shipping charges"
+  #     end
+  #   end
+  #
+  # You may associate line items of any type with credit notes and invoices interchangeably. This
+  # means, for example, that if you overcharge a customer for shipping, you can send them a credit
+  # note with a +ShippingCharges+ line item, thus making it explicit what it is you are refunding.
+  # On a credit note/refund the line item's +net_amount+ and +tax_amount+ should be negative.
+  # +Payment+ records usually do not have any associated line items.
+  #
+  # == Required methods/database columns
+  #
+  # The following methods/database columns are <b>required</b> for +LineItem+ objects (you may give them
+  # different names, but then you need to tell +acts_as_line_item+ about your custom names):
+  #
+  # +type+::
+  #   String to store the class name, for ActiveRecord single table inheritance.
+  #  
+  # +ledger_item+::
+  #   You should define an association <tt>belongs_to :ledger_item, ...</tt> which returns the
+  #   +LedgerItem+ object (invoice/credit note) to which this line item belongs.
+  #  
+  # +ledger_item_id+::
+  #   A foreign key of integer type, which stores the ID of the model object returned by the
+  #   +ledger_item+ association.
+  #
+  # +net_amount+::
+  #   A decimal column containing the monetary amount charged by this line item, not including tax.
+  #   The value is typically positive on an invoice and negative on a credit note. The currency is
+  #   not explicitly specified on the line item, but is taken to be the currency of the invoice or
+  #   credit note to which it belongs. (This is deliberate, because you mustn't mix different
+  #   currencies within one invoice.) See the documentation of the +CurrencyValue+ module for notes
+  #   on suitable datatypes for monetary values. +acts_as_currency_value+ is automatically applied
+  #   to this attribute.
+  #   
+  # +tax_amount+::
+  #   A decimal column containing the monetary amount of tax which is added to +net_amount+ to
+  #   obtain the total price. This may of course be zero if no tax applies; otherwise it should have
+  #   the same sign as +net_amount+. +CurrencyValue+ applies as with +net_amount+. If you have
+  #   several different taxes being applied, please check with your accountant. We suggest that you
+  #   put VAT or sales tax in this +tax_amount+ column, and any other taxes (e.g. duty on alcohol or
+  #   tobacco, or separate state/city taxes) in separate line items. If you are not obliged to pay
+  #   tax, lucky you -- put zeroes in this column and await the day when you have enough business
+  #   that you *do* have to pay tax.
+  #
+  # +description+::
+  #   A method which returns a short string explaining to your user what this line item is for.
+  #   Can be a database column but doesn't have to be.
+  #
+  # == Optional methods/database columns
+  #
+  # The following methods/database columns are <b>optional, but recommended</b> for +LineItem+ objects:
+  #
+  # +uuid+::
+  #   A Universally Unique Identifier (UUID)[http://en.wikipedia.org/wiki/UUID] string for this line item.
+  #   It may seem unnecessary now, but may help you to keep track of your data later on as your system
+  #   grows. If you have the +uuid+ gem installed and this column is present, a UUID is automatically
+  #   generated when you create a new line item.
+  #
+  # +tax_point+::
+  #   A datetime column which indicates the date on which the sale is made and/or the service is provided.
+  #   It is related to the +issue_date+ on the associated invoice/credit note, but does not necessarily
+  #   have the same value. The exact technicalities will vary by jurisdiction, but generally this is the
+  #   point in time which determines into which month or which tax period you count a sale. The value may
+  #   be the same as +created_at+ or +updated_at+, but not necessarily.
+  #
+  # +tax_rate_id+, +tax_rate+::
+  #   +tax_rate_id+ is a foreign key of integer type, and +tax_rate+ is a +belongs_to+ association
+  #   based on it. It refers to another model in your application which represents the tax rate
+  #   applied to this line item. The tax rate model object should use +acts_as_tax_rate+. This
+  #   attribute is necessary if you want tax calculations to be performed automatically.
+  #
+  # +price_id+, +price+::
+  #   +price_id+ is a foreign key of integer type, and +price+ is a +belongs_to+ association based
+  #   on it. It refers to another model in your application which represents the unit price (e.g. a
+  #   reference to a the product, or to a particular price band of a service). The model object thus
+  #   referred to should use +acts_as_price+. This attribute allows you to get better reports of how
+  #   much you sold of what.
+  #
+  # +quantity+::
+  #   A numeric (integer or decimal) type, saying how many units of a particular product or service
+  #   this line item represents. Default is 1. Note that if you specify a +quantity+, the values for
+  #   +net_amount+ and +tax_amount+ must be the cost of the given quantity as a whole; if you need
+  #   to display the unit price, you can get it by dividing +net_amount+ by +quantity+, or by
+  #   referring to the +price+ association.
+  #
+  # +creator_id+::
+  #   The ID of the user whose action caused this line item to be created or updated. This can be useful
+  #   for audit trail purposes, particularly if you allow multiple users of your application to act on
+  #   behalf of the same customer organisation.
+  #
+  # +created_at+, +updated_at+::
+  #   These standard datetime columns are also recommended.
+  #
+  module LineItem
+    module ActMethods
+      # Declares that the current class is a model for line items (i.e. individual items on invoices
+      # and credit notes).
+      #
+      # The name of any attribute or method required by +LineItem+ (as documented on the
+      # +LineItem+ module) may be used as an option, with the value being the name under which
+      # that particular method or attribute can be found. This allows you to use names other than
+      # the defaults. For example, if your database column storing the line item value is called
+      # +net_price+ instead of +net_amount+:
+      #
+      #   acts_as_line_item :net_amount => :net_price
+      def acts_as_line_item(*args)
+        Invoicing::ClassInfo.acts_as(Invoicing::LineItem, self, args)
+        
+        info = line_item_class_info
+        if info.previous_info.nil? # Called for the first time?
+          # Set the 'amount' columns to act as currency values
+          acts_as_currency_value(info.method(:net_amount), info.method(:tax_amount))
+          
+          extend Invoicing::FindSubclasses
+          
+          # Dynamically created named scopes
+          named_scope :in_effect, lambda{
+            ledger_assoc_id = line_item_class_info.method(:ledger_item).to_sym
+            ledger_refl = reflections[ledger_assoc_id]
+            ledger_table = ledger_refl.table_name # not quoted_table_name because it'll be quoted again
+            status_column = ledger_refl.klass.send(:ledger_item_class_info).method(:status)
+            { :joins => ledger_assoc_id,
+              :conditions => {"#{ledger_table}.#{status_column}" => ['closed', 'cleared'] } }
+          }
+          
+          named_scope :sorted, lambda{|column|
+            column = line_item_class_info.method(column).to_s
+            if column_names.include?(column)
+              {:order => "#{connection.quote_column_name(column)}, #{connection.quote_column_name(primary_key)}"}
+            else
+              {:order => connection.quote_column_name(primary_key)}
+            end
+          }
+        end
+      end
+    end
+    
+    # Overrides the default constructor of <tt>ActiveRecord::Base</tt> when +acts_as_line_item+
+    # is called. If the +uuid+ gem is installed, this constructor creates a new UUID and assigns
+    # it to the +uuid+ property when a new line item model object is created.
+    def initialize(*args)
+      super
+      # Initialise uuid attribute if possible
+      info = line_item_class_info
+      if self.has_attribute?(info.method(:uuid)) && info.uuid_generator
+        write_attribute(info.method(:uuid), info.uuid_generator.generate)
+      end
+    end
+
+    # Returns the currency code of the ledger item to which this line item belongs.
+    def currency
+      ledger_item = line_item_class_info.get(self, :ledger_item)
+      raise RuntimeError, 'Cannot determine currency for line item without a ledger item' if ledger_item.nil?
+      ledger_item.send(:ledger_item_class_info).get(ledger_item, :currency)
+    end
+    
+    # The sum of +net_amount+ and +tax_amount+.
+    def gross_amount
+      net_amount = line_item_class_info.get(self, :net_amount)
+      tax_amount = line_item_class_info.get(self, :tax_amount)
+      (net_amount && tax_amount) ? (net_amount + tax_amount) : nil
+    end
+
+    # +gross_amount+ formatted in human-readable form using the line item's currency.
+    def gross_amount_formatted
+      format_currency_value(gross_amount)
+    end
+    
+    # We don't actually implement anything using +method_missing+ at the moment, but use it to
+    # generate slightly more useful error messages in certain cases.
+    def method_missing(method_id, *args)
+      method_name = method_id.to_s
+      if ['ledger_item', line_item_class_info.method(:ledger_item)].include? method_name
+        raise RuntimeError, "You need to define an association like 'belongs_to :ledger_item' on #{self.class.name}. If you " +
+          "have defined the association with a different name, pass the option :ledger_item => :your_association_name to " +
+          "acts_as_line_item."
+      else
+        super
+      end
+    end
+    
+    
+    # Stores state in the ActiveRecord class object
+    class ClassInfo < Invoicing::ClassInfo::Base #:nodoc:
+      attr_reader :uuid_generator
+      
+      def initialize(model_class, previous_info, args)
+        super
+        
+        begin # try to load the UUID gem
+          require 'uuid'
+          @uuid_generator = UUID.new
+        rescue LoadError, NameError # silently ignore if gem not found
+          @uuid_generator = nil
+        end
+      end
+      
+      # Allow methods generated by +CurrencyValue+ to be renamed as well
+      def method(name)
+        if name.to_s =~ /^(.*)_formatted$/
+          "#{super($1)}_formatted"
+        else
+          super
+        end
+      end
+    end
+  end
+end