invoicing 0.1.0

data/lib/invoicing/ledger_item.rb

@@ -0,0 +1,718 @@
+module Invoicing
+  # = Ledger item objects
+  #
+  # This module implements a simple ledger, i.e. the record of all of the business transactions
+  # which are handled by your application. Each transaction is recorded as one +LedgerItem+ object,
+  # each of which may have one of the following three types:
+  #
+  # +Invoice+::
+  #   When you send an invoice to someone (= a customer), this is a record of the fact
+  #   that you have sold them something (a product, a service etc.), and how much you expect to be
+  #   paid for it. An invoice can consist of a list of individual charges, but it is considered as
+  #   one document for legal purposes. You can also create invoices from someone else to yourself,
+  #   if you owe someone else money -- for example, if you need to pay commissions to a reseller of
+  #   your application.
+  # +CreditNote+::
+  #   This is basically a invoice for a negative amount; you should use it if you have previously
+  #   sent a customer an invoice with an amount which was too great (i.e. you have overcharged them).
+  #   The numeric values stored in the database for a credit note are negative, to make it easier to
+  #   calculate account summaries, but they may be formatted as positive values when presented to
+  #   users if that is customary in your country. For example, if you send a customer an invoice
+  #   with a +total_amount+ of $20 and a credit note with a +total_amount+ of -$10, that means that
+  #   overall you're asking them to pay $10.
+  # +Payment+::
+  #   This is a record of the fact that a payment has been made. It's a simple object, in effect just
+  #   saying that party A paid amount X to party B on date Y. This module does not implement any
+  #   particular payment mechanism such as credit card handling, although it could be implemented on
+  #   top of a +Payment+ object.
+  #
+  # == Important principles
+  #
+  # Note the distinction between Invoices/Credit Notes and Payments; to keep your accounts clean,
+  # it is important that you do not muddle these up.
+  #
+  # * <b>Invoices and Credit Notes</b> are the important documents for tax purposes in most
+  #   jurisdictions. They record the date on which the sale is officially made, and that date
+  #   determines which tax rates apply. An invoice often also represents the transfer of ownership from
+  #   the supplier to the customer; for example, if you ask your customers to send payment in
+  #   advance (such as 'topping up' their account), that money still belongs to your customer
+  #   until the point where they have used your service, and you have charged them for your
+  #   service by sending them an invoice. You should only invoice them for what they have actually
+  #   used, then the remaining balance will automatically be retained on their account.
+  # * <b>Payments</b> are just what it says on the tin -- the transfer of money from one hand
+  #   to another. A payment may occur before an invoice is issued (payment in advance), or
+  #   after/at the same time as an invoice is issued to settle the debt (payment in arrears, giving
+  #   your customers credit). You can choose whatever makes sense for your business.
+  #   Payments may often be associated one-to-one with invoices, but not necessarily -- an invoice
+  #   may be paid in instalments, or several invoices may be lumped together to one payment. Your
+  #   customer may even refuse to pay some charges, in which case there is an invoice but no payment
+  #   (until at some point you either reverse it with a credit note, or write it off as bad debt,
+  #   but that's beyond our scope right now).
+  #
+  # Another very important principle is that once a piece of information has been added to the
+  # ledger, you <b>should not modify or delete it</b>. Particularly when you have 'sent' one of your
+  # customers or suppliers a document (which may mean simply that they have seen it on the web) you should
+  # not change it again, because they might have added that information to their own accounting system.
+  # Changing any information is guaranteed to lead to confusion. (The model objects do not restrict your
+  # editing capabilities because they might be necessary in specific circumstances, but you should be
+  # extremely careful when changing anything.)
+  #
+  # Of course you make mistakes or change your mind, but please deal with them cleanly:
+  # * If you create an invoice whose value is too small, don't amend the invoice, but send them
+  #   another invoice to cover the remaining amount.
+  # * If you create an invoice whose value is too great (for example because you want to offer one
+  #   customer a special discount), don't amend the invoice, but send them a credit note to waive
+  #   your claim to the difference.
+  # * If you create a payment, mark it as +pending+ until it the money has actually arrived.
+  #   If it never arrives, keep the record but mark it as +failed+ in case you need to investigate
+  #   it later.
+  #
+  # The exception to the 'no modifications' rule are invoices on which you accumulate charges
+  # (e.g. over the course of a month)
+  # and then officially 'send' the invoice at the end of the period. In this gem we call such
+  # invoices +open+ while they may still be changed. It's ok to add charges to +open+ invoices
+  # as you go along; while it is +open+ it is not legally an invoice, but only a statement
+  # of accumulated charges. If you display it to users, make sure that you don't call it "invoice",
+  # to avoid confusion. Only when you set it to +closed+ at the end of the month does the
+  # statement become an invoice for legal purposes. Once it's +closed+ you must not add
+  # any further charges to it.
+  #
+  # Finally, each ledger item has a sender and a recipient; typically one of the two will be
+  # <b>you</b> (the person/organsation who owns/operates the application):
+  # * For invoices, credit notes and payments between you and your customers, set the sender
+  #   to be yourself and the recipient to be your customer;
+  # * If you use this system to record suppliers, set the sender to be your supplier and the
+  #   recipient to be yourself.
+  # (See below for details.) It is perfectly ok to have documents which are sent between your
+  # users, where you are neither sender nor recipient; this may be useful if you want to allow
+  # users to trade directly with each other.
+  #
+  # == Using invoices, credit notes and payments in your application
+  #
+  # All invoices, credit notes and payments (collectively called 'ledger items') are stored in a
+  # single database table. We use <b>single table inheritance</b> to distinguish the object types.
+  # You need to create at least the following four model classes in your application:
+  #
+  #   class LedgerItem < ActiveRecord::Base
+  #     acts_as_ledger_item
+  #   end
+  #
+  #   class Invoice < LedgerItem                      # Base class for all types of invoice
+  #     acts_as_ledger_item :subtype => :invoice
+  #   end
+  #
+  #   class CreditNote < LedgerItem                   # Base class for all types of credit note
+  #     acts_as_ledger_item :subtype => :credit_note
+  #   end
+  #
+  #   class Payment < LedgerItem                      # Base class for all types of payment
+  #     acts_as_ledger_item :subtype => :payment
+  #   end
+  #
+  # You may give the classes different names than these, and you can package them in modules if
+  # you wish, but they need to have the <tt>:subtype => ...</tt> option parameters as above.
+  #
+  # You can create as many subclasses as you like of each of Invoice, CreditNote and Payment. This
+  # provides a convenient mechanism for encapsulating different types of functionality which you
+  # may need for different types of transactions, but still keeping the accounts in one place. You
+  # may start with only one subclass of +Invoice+ (e.g. <tt>class MonthlyChargesInvoice < Invoice</tt>
+  # to bill users for their use of your application; but as you want to do more clever things, you
+  # can add other subclasses of +Invoice+ as and when you need them (such as +ConsultancyServicesInvoice+
+  # and +SalesCommissionInvoice+, for example). Similarly for payments, you may have subclasses
+  # representing credit card payments, cash payments, bank transfers etc.
+  #
+  # Please note that the +Payment+ ledger item type does not itself implement any particular
+  # payment methods such as credit card handling; however, for third-party libraries providing
+  # credit card handling, this would be a good place to integrate.
+  #
+  # The model classes must have a certain minimum set of columns and a few common methods, documented
+  # below (although you may rename any of them if you wish). Beyond those, you may add other methods and
+  # database columns for your application's own needs, provided they don't interfere with names used here.
+  #
+  # == Required methods/database columns
+  #
+  # The following methods/database columns are <b>required</b> for +LedgerItem+ objects (you may give them
+  # different names, but then you need to tell +acts_as_ledger_item+ about your custom names):
+  #
+  # +type+::
+  #   String to store the class name, for ActiveRecord single table inheritance.
+  #
+  # +sender_id+::
+  #   Integer-valued foreign key, used to refer to some other model object representing the party
+  #   (person, company etc.) who is the sender of the transaction.
+  #   - In the case of an invoice or credit note, the +sender_id+ identifies the supplier of the product or service,
+  #     i.e. the person who is owed the amount specified on the invoice, also known as the creditor.
+  #   - In the case of a payment record, the +sender_id+ identifies the payee, i.e. the person who sends the note
+  #     confirming that they received payment.
+  #   - This field may be +NULL+ to refer to yourself (i.e. the company/person who owns or
+  #     operates this application), but you may also use non-+NULL+ values to refer to yourself. It's just
+  #     important that you consistently refer to the same party by the same value in different ledger items.
+  #
+  # +recipient_id+::
+  #   The counterpart to +sender_id+: foreign key to a model object which represents the
+  #   party who is the recipient of the transaction.
+  #   - In the case of an invoice or credit note, the +recipient_id+ identifies the customer/buyer of the product or
+  #     service, i.e. the person who owes the amount specified on the invoice, also known as the debtor.
+  #   - In the case of a payment record, the +recipient_id+ identifies the payer, i.e. the recipient of the
+  #     payment receipt.
+  #   - +NULL+ may be used as in +sender_id+.
+  #
+  # +sender_details+::
+  #   A method (does not have to be a database column) which returns a hash with information
+  #   about the party identified by +sender_id+. See the documentation of +sender_details+ for the expected
+  #   contents of the hash. Must always return valid details, even if +sender_id+ is +NULL+.
+  #
+  # +recipient_details+::
+  #   A method (does not have to be a database column) which returns a hash with information
+  #   about the party identified by +recipient_id+. See the documentation of +sender_details+ for the expected
+  #   contents of the hash (+recipient_details+ uses the same format as +sender_details+). Must always
+  #   return valid details, even if +recipient_id+ is +NULL+.
+  #
+  # +identifier+::
+  #   A number or string used to identify this record, i.e. the invoice number, credit note number or
+  #   payment receipt number as appropriate.
+  #   - There may be legal requirements in your country concerning its format, but as long as it uniquely identifies
+  #     the document within your organisation you should be safe.
+  #   - It's possible to simply make this an alias of the primary key, but it's strongly recommended that you use a
+  #     separate database column. If you ever need to generate invoices on behalf of other people (i.e. where
+  #     +sender_id+ is not you), you need to give the sender of the invoice the opportunity to enter their own
+  #     +identifier+ (because it then must be unique within the sender's organisation, not yours).
+  #
+  # +issue_date+::
+  #   A datetime column which indicates the date on which the document is issued, and which may also
+  #   serve as the tax point (the date which determines which tax rate is applied). This should be a separate
+  #   column, because it won't necessarily be the same as +created_at+ or +updated_at+. There may be business
+  #   reasons for choosing particular dates, but the date at which you send the invoice or receive the payment
+  #   should do unless your accountant advises you otherwise.
+  #
+  # +currency+::
+  #   The 3-letter code which identifies the currency used in this transaction; must be one of the list
+  #   of codes in ISO-4217[http://en.wikipedia.org/wiki/ISO_4217]. (Even if you only use one currency throughout
+  #   your site, this is needed to format monetary amounts correctly.)
+  #
+  # +total_amount+::
+  #   A decimal column containing the grand total monetary sum (of the invoice or credit note), or the monetary
+  #   amount paid (of the payment record), including all taxes, charges etc. For invoices and credit notes, a
+  #   +before_validation+ filter is automatically invoked, which adds up the +net_amount+ and +tax_amount+ values
+  #   of all line items and assigns that sum to +total_amount+. For payment records, which do not usually have
+  #   line items, you must assign the correct value to this column. 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+::
+  #   If you're a small business you maybe don't need to add tax to your invoices; but if you are successful,
+  #   you almost certainly will need to do so eventually. In most countries this takes the form of Value Added
+  #   Tax (VAT) or Sales Tax. For invoices and credit notes, you must store the amount of tax in this table;
+  #   a +before_validation+ filter is automatically invoked, which adds up the +tax_amount+ values of all
+  #   line items and assigns that sum to +total_amount+. For payment records this should be zero (unless you
+  #   use a cash accounting scheme, which is currently not supported). 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.
+  #
+  # +status+::
+  #   A string column used to keep track of the status of ledger items. Currently the following values are defined
+  #   (but future versions may add further +status+ values):
+  #   +open+::      For invoices/credit notes: the document is not yet finalised, further line items may be added.
+  #   +closed+::    For invoices/credit notes: the document has been sent to the recipient and will not be changed again.
+  #   +cancelled+:: For invoices/credit notes: the document has been declared void and does not count towards accounts.
+  #                 (Use this sparingly; if you want to refund an invoice that has been sent, send a credit note.)
+  #   +pending+::   For payments: payment is expected or has been sent, but has not yet been confirmed as received.
+  #   +cleared+::   For payments: payment has completed successfully.
+  #   +failed+::    For payments: payment did not succeed; this record is not counted towards accounts.
+  #
+  # +description+::
+  #   A method which returns a short string describing what this invoice, credit note or payment is about.
+  #   Can be a database column but doesn't have to be.
+  #
+  # +line_items+::
+  #   You should define an association <tt>has_many :line_items, ...</tt> referring to the +LineItem+ objects
+  #   associated with this ledger item.
+  #
+  #
+  # == Optional methods/database columns
+  #
+  # The following methods/database columns are <b>optional, but recommended</b> for +LedgerItem+ objects:
+  #
+  # +period_start+, +period_end+::
+  #   Two datetime columns which define the period of time covered by an invoice or credit note. If the thing you
+  #   are selling is a one-off, you can omit these columns or leave them as +NULL+. However, if there is any sort
+  #   of duration associated with an invoice/credit note (e.g. charges incurred during a particular month, or
+  #   an annual subscription, or a validity period of a license, etc.), please store that period here. It's
+  #   important for accounting purposes. (For +Payment+ objects it usually makes most sense to just leave these
+  #   as +NULL+.)
+  #
+  # +uuid+::
+  #   A Universally Unique Identifier (UUID)[http://en.wikipedia.org/wiki/UUID] string for this invoice, credit
+  #   note or payment. 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 ledger item.
+  #
+  # +due_date+::
+  #   The date at which the invoice or credit note is due for payment. +nil+ on +Payment+ records.
+  #
+  # +created_at+, +updated_at+::
+  #   The standard ActiveRecord datetime columns for recording when an object was created and last changed.
+  #   The values are not directly used at the moment, but it's useful information in case you need to track down
+  #   a particular transaction sometime; and ActiveRecord manages them for you anyway.
+  #
+  #
+  # == Generated methods
+  #
+  # In return for providing +LedgerItem+ with all the required information as documented above, you are given
+  # a number of class and instance methods which you will find useful sooner or later. In addition to those
+  # documented in this module (instance methods) and <tt>Invoicing::LedgerItem::ClassMethods</tt>
+  # (class methods), the following methods are generated dynamically:
+  #
+  # +sent_by+::     Named scope which takes a person/company ID and matches all ledger items whose
+  #                 +sender_id+ matches that value.
+  # +received_by+:: Named scope which takes a person/company ID and matches all ledger items whose
+  #                 +recipient_id+ matches that value.
+  # +sent_or_received_by+:: Union of +sent_by+ and +received_by+.
+  # +in_effect+::   Named scope which matches all closed invoices/credit notes (not open or cancelled)
+  #                 and all cleared payments (not pending or failed). You probably want to use this
+  #                 quite often, for all reporting purposes.
+  # +open_or_pending+::     Named scope which matches all open invoices/credit notes and all pending
+  #                         payments.
+  # +due_at+::      Named scope which takes a +DateTime+ argument and matches all ledger items whose
+  #                 +due_date+ value is either +NULL+ or is not after the given time. For example,
+  #                 you could run <tt>LedgerItem.due_at(Time.now).account_summaries</tt>
+  #                 once a day and process payment for all accounts whose balance is not zero.
+  # +sorted+::      Named scope which takes a column name as documented above (even if it has been
+  #                 renamed), and sorts the query by that column. If the column does not exist,
+  #                 silently falls back to sorting by the primary key.
+  # +exclude_empty_invoices+:: Named scope which excludes any invoices or credit notes which do not
+  #                            have any associated line items (payments without line items are
+  #                            included though). If you're chaining scopes it would be advantageous
+  #                            to put this one close to the beginning of your scope chain.
+  module LedgerItem
+    
+    module ActMethods
+      # Declares that the current class is a model for ledger items (i.e. invoices, credit notes and
+      # payment notes).
+      #
+      # This method accepts a hash of options, all of which are optional:
+      # <tt>:subtype</tt>:: One of <tt>:invoice</tt>, <tt>:credit_note</tt> or <tt>:payment</tt>.
+      #
+      # Also, the name of any attribute or method required by +LedgerItem+ (as documented on the
+      # +LedgerItem+ 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 invoice value is called
+      # +gross_amount+ instead of +total_amount+:
+      #
+      #   acts_as_ledger_item :total_amount => :gross_amount
+      def acts_as_ledger_item(*args)
+        Invoicing::ClassInfo.acts_as(Invoicing::LedgerItem, self, args)
+        
+        info = ledger_item_class_info
+        return unless info.previous_info.nil? # Called for the first time?
+        
+        before_validation :calculate_total_amount
+        
+        # Set the 'amount' columns to act as currency values
+        acts_as_currency_value(info.method(:total_amount), info.method(:tax_amount),
+          :currency => info.method(:currency))
+        
+        extend Invoicing::FindSubclasses
+        include Invoicing::LedgerItem::RenderHTML
+        include Invoicing::LedgerItem::RenderUBL
+        
+        # Dynamically created named scopes
+        named_scope :sent_by, lambda{ |sender_id|
+          { :conditions => {info.method(:sender_id) => sender_id} }
+        }
+        
+        named_scope :received_by, lambda{ |recipient_id|
+          { :conditions => {info.method(:recipient_id) => recipient_id} }
+        }
+        
+        named_scope :sent_or_received_by, lambda{ |sender_or_recipient_id|
+          sender_col = connection.quote_column_name(info.method(:sender_id))
+          recipient_col = connection.quote_column_name(info.method(:recipient_id))
+          { :conditions => ["#{sender_col} = ? OR #{recipient_col} = ?",
+                            sender_or_recipient_id, sender_or_recipient_id] }
+        }
+        
+        named_scope :in_effect, :conditions => {info.method(:status) => ['closed', 'cleared']}
+        
+        named_scope :open_or_pending, :conditions => {info.method(:status) => ['open', 'pending']}
+        
+        named_scope :due_at, lambda{ |date|
+          due_date = connection.quote_column_name(info.method(:due_date))
+          {:conditions => ["#{due_date} <= ? OR #{due_date} IS NULL", date]}
+        }
+        
+        named_scope :sorted, lambda{|column|
+          column = ledger_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
+        }
+        
+        named_scope :exclude_empty_invoices, lambda{
+          line_items_assoc_id = info.method(:line_items).to_sym
+          line_items_refl = reflections[line_items_assoc_id]
+          line_items_table = line_items_refl.quoted_table_name
+          
+          # e.g. `ledger_items`.`id`
+          ledger_items_id = quoted_table_name + "." + connection.quote_column_name(primary_key)
+          
+          # e.g. `line_items`.`id`
+          line_items_id = line_items_table + "." +
+            connection.quote_column_name(line_items_refl.klass.primary_key)
+          
+          # e.g. `line_items`.`ledger_item_id`
+          ledger_item_foreign_key = line_items_table + "." + connection.quote_column_name(
+            line_items_refl.klass.send(:line_item_class_info).method(:ledger_item_id))
+          
+          payment_classes = select_matching_subclasses(:is_payment, true).map{|c| c.name}
+          is_payment_class = merge_conditions({info.method(:type) => payment_classes})
+          
+          subquery = construct_finder_sql(
+            :select => "#{quoted_table_name}.*, COUNT(#{line_items_id}) AS number_of_line_items",
+            :joins => "LEFT JOIN #{line_items_table} ON #{ledger_item_foreign_key} = #{ledger_items_id}",
+            :group => Invoicing::ConnectionAdapterExt.group_by_all_columns(self)
+          )
+            
+          {:from => "(#{subquery}) AS #{quoted_table_name}",
+           :conditions => "number_of_line_items > 0 OR #{is_payment_class}"}
+        }
+      end # def acts_as_ledger_item
+      
+      # Synonym for <tt>acts_as_ledger_item :subtype => :invoice</tt>. All options other than
+      # <tt>:subtype</tt> are passed on to +acts_as_ledger_item+. You should apply
+      # +acts_as_invoice+ only to a model which is a subclass of an +acts_as_ledger_item+ type.
+      def acts_as_invoice(options={})
+        acts_as_ledger_item(options.clone.update({:subtype => :invoice}))
+      end
+      
+      # Synonym for <tt>acts_as_ledger_item :subtype => :credit_note</tt>. All options other than
+      # <tt>:subtype</tt> are passed on to +acts_as_ledger_item+. You should apply
+      # +acts_as_credit_note+ only to a model which is a subclass of an +acts_as_ledger_item+ type.
+      def acts_as_credit_note(options={})
+        acts_as_ledger_item(options.clone.update({:subtype => :credit_note}))
+      end
+      
+      # Synonym for <tt>acts_as_ledger_item :subtype => :payment</tt>. All options other than
+      # <tt>:subtype</tt> are passed on to +acts_as_ledger_item+. You should apply
+      # +acts_as_payment+ only to a model which is a subclass of an +acts_as_ledger_item+ type.
+      def acts_as_payment(options={})
+        acts_as_ledger_item(options.clone.update({:subtype => :payment}))
+      end
+    end # module ActMethods
+    
+    # Overrides the default constructor of <tt>ActiveRecord::Base</tt> when +acts_as_ledger_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 ledger item model object is created.
+    def initialize(*args)
+      super
+      # Initialise uuid attribute if possible
+      info = ledger_item_class_info
+      if self.has_attribute?(info.method(:uuid)) && info.uuid_generator
+        write_attribute(info.method(:uuid), info.uuid_generator.generate)
+      end
+    end
+    
+    # Calculate sum of net_amount and tax_amount across all line items, and assign it to total_amount;
+    # calculate sum of tax_amount across all line items, and assign it to tax_amount.
+    # Called automatically as a +before_validation+ callback.
+    def calculate_total_amount
+      net_total = tax_total = BigDecimal('0')
+      line_items = ledger_item_class_info.get(self, :line_items)
+      
+      line_items.each do |line|
+        info = line.send(:line_item_class_info)
+        
+        # Make sure ledger_item association is assigned -- the CurrencyValue
+        # getters depend on it to fetch the currency
+        info.set(line, :ledger_item, self)
+        net_amount = info.get(line, :net_amount)
+        tax_amount = info.get(line, :tax_amount)
+        net_total += net_amount unless net_amount.nil?
+        tax_total += tax_amount unless tax_amount.nil?
+      end
+      
+      ledger_item_class_info.set(self, :total_amount, net_total + tax_total)
+      ledger_item_class_info.set(self, :tax_amount,   tax_total)
+    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 ['line_items', ledger_item_class_info.method(:line_items)].include? method_name
+        raise RuntimeError, "You need to define an association like 'has_many :line_items' on #{self.class.name}. If you " +
+          "have defined the association with a different name, pass the option :line_items => :your_association_name to " +
+          "acts_as_ledger_item."
+      else
+        super
+      end
+    end
+
+    # The difference +total_amount+ minus +tax_amount+.
+    def net_amount
+      total_amount = ledger_item_class_info.get(self, :total_amount)
+      tax_amount   = ledger_item_class_info.get(self, :tax_amount)
+      (total_amount && tax_amount) ? (total_amount - tax_amount) : nil
+    end
+    
+    # +net_amount+ formatted in human-readable form using the ledger item's currency.
+    def net_amount_formatted
+      format_currency_value(net_amount)
+    end
+    
+    
+    # You must overwrite this method in subclasses of +Invoice+, +CreditNote+ and +Payment+ so that it returns
+    # details of the party sending the document. See +sender_id+ above for a detailed interpretation of
+    # sender and receiver.
+    #
+    # The methods +sender_details+ and +recipient_details+ are required to return hashes
+    # containing details about the sender and recipient of an invoice, credit note or payment. The reason we
+    # do this is that you probably already have your own system for handling users, customers and their personal
+    # or business details, and this framework shouldn't require you to change any of that.
+    #
+    # The invoicing framework currently uses these details only for rendering invoices and credit notes, but
+    # in future it may serve more advanced purposes, such as determining which tax rate to apply for overseas
+    # customers.
+    #
+    # In the hash returned by +sender_details+ and +recipient_details+, the following keys are recognised --
+    # please fill in as many as possible:
+    # <tt>:is_self</tt>::      +true+ if these details refer to yourself, i.e. the person or organsiation who owns/operates
+    #                          this application. +false+ if these details refer to any other party.
+    # <tt>:name</tt>::         The name of the person or organisation whose billing address is defined below.
+    # <tt>:contact_name</tt>:: The name of a person/department within the organisation named by <tt>:name</tt>.
+    # <tt>:address</tt>::      The body of the billing address (not including city, postcode, state and country); may be
+    #                          a multi-line string, with lines separated by '\n' line breaks.
+    # <tt>:city</tt>::         The name of the city or town in the billing address.
+    # <tt>:state</tt>::        The state/region/province/county of the billing address as appropriate.
+    # <tt>:postal_code</tt>::  The postal code of the billing address (e.g. ZIP code in the US).
+    # <tt>:country</tt>::      The billing address country (human-readable).
+    # <tt>:country_code</tt>:: The two-letter country code of the billing address, according to
+    #                          ISO-3166-1[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2].
+    # <tt>:tax_number</tt>::   The Value Added Tax registration code of this person or organisation, if they have
+    #                          one, preferably including the country identifier at the beginning. This is important for
+    #                          transactions within the European Union.
+    def sender_details
+      raise 'overwrite this method'
+    end
+    
+    # You must overwrite this method in subclasses of +Invoice+, +CreditNote+ and +Payment+ so that it returns
+    # details of the party receiving the document. See +recipient_id+ above for a detailed interpretation of
+    # sender and receiver. See +sender_details+ for a list of fields to return in the hash.
+    def recipient_details
+      raise 'overwrite this method'
+    end
+    
+    # Returns +true+ if this document was sent by the user with ID +user_id+. If the argument is +nil+
+    # (indicating yourself), this also returns +true+ if <tt>sender_details[:is_self]</tt>.
+    def sent_by?(user_id)
+      (ledger_item_class_info.get(self, :sender_id) == user_id) ||
+        !!(user_id.nil? && ledger_item_class_info.get(self, :sender_details)[:is_self])
+    end
+    
+    # Returns +true+ if this document was received by the user with ID +user_id+. If the argument is +nil+
+    # (indicating yourself), this also returns +true+ if <tt>recipient_details[:is_self]</tt>.
+    def received_by?(user_id)
+      (ledger_item_class_info.get(self, :recipient_id) == user_id) ||
+        !!(user_id.nil? && ledger_item_class_info.get(self, :recipient_details)[:is_self])
+    end
+    
+    # Returns a boolean which specifies whether this transaction should be recorded as a debit (+true+)
+    # or a credit (+false+) on a particular ledger. Unless you know what you are doing, you probably
+    # do not need to touch this method.
+    #
+    # It takes an argument +self_id+, which should be equal to either +sender_id+ or +recipient_id+ of this
+    # object, and which determines from which perspective the account is viewed. The default behaviour is:
+    # * A sent invoice (<tt>self_id == sender_id</tt>) is a debit since it increases the recipient's
+    #   liability; a sent credit note decreases the recipient's liability with a negative-valued
+    #   debit; a sent payment receipt is a positive-valued credit and thus decreases the recipient's
+    #   liability.
+    # * A received invoice (<tt>self_id == recipient_id</tt>) is a credit because it increases your own
+    #   liability; a received credit note decreases your own liability with a negative-valued credit;
+    #   a received payment receipt is a positive-valued debit and thus decreases your own liability.
+    #
+    # Note that accounting practices differ with regard to credit notes: some think that a sent
+    # credit note should be recorded as a positive credit (hence the name 'credit note'); others
+    # prefer to use a negative debit. We chose the latter because it allows you to calculate the
+    # total sale volume on an account simply by adding up all the debits. If there is enough demand
+    # for the positive-credit model, we may add support for it sometime in future.
+    def debit?(self_id)
+      sender_is_self = sent_by?(self_id)
+      recipient_is_self = received_by?(self_id)
+      raise ArgumentError, "self_id #{self_id.inspect} is neither sender nor recipient" unless sender_is_self || recipient_is_self
+      raise ArgumentError, "self_id #{self_id.inspect} is both sender and recipient" if sender_is_self && recipient_is_self
+      self.class.debit_when_sent_by_self ? sender_is_self : recipient_is_self
+    end
+    
+    
+    module ClassMethods
+      # Returns +true+ if this type of ledger item should be recorded as a debit when the party
+      # viewing the account is the sender of the document, and recorded as a credit when
+      # the party viewing the account is the recipient. Returns +false+ if those roles are
+      # reversed. This method implements default behaviour for invoices, credit notes and
+      # payments (see <tt>Invoicing::LedgerItem#debit?</tt>); if you define custom ledger item
+      # subtypes (other than +invoice+, +credit_note+ and +payment+), you should override this
+      # method accordingly in those subclasses.
+      def debit_when_sent_by_self
+        case ledger_item_class_info.subtype
+          when :invoice     then true
+          when :credit_note then true
+          when :payment     then false
+          else nil
+        end
+      end
+      
+      # Returns +true+ if this type of ledger item is a +invoice+ subtype, and +false+ otherwise.
+      def is_invoice
+        ledger_item_class_info.subtype == :invoice
+      end
+      
+      # Returns +true+ if this type of ledger item is a +credit_note+ subtype, and +false+ otherwise.
+      def is_credit_note
+        ledger_item_class_info.subtype == :credit_note
+      end
+      
+      # Returns +true+ if this type of ledger item is a +payment+ subtype, and +false+ otherwise.
+      def is_payment
+        ledger_item_class_info.subtype == :payment
+      end
+      
+      # Returns a summary of the customer or supplier account between two parties identified
+      # by +self_id+ (the party from whose perspective the account is seen, 'you') and +other_id+
+      # ('them', your supplier/customer). The return value is a hash with the following structure:
+      #
+      #   { :GBP => {                                 # ISO 4217 currency code for the following figures
+      #       :sales             => BigDecimal(...),  # Sum of sales (invoices sent by self_id)
+      #       :purchases         => BigDecimal(...),  # Sum of purchases (invoices received by self_id)
+      #       :sale_receipts     => BigDecimal(...),  # Sum of payments received from customer
+      #       :purchase_payments => BigDecimal(...),  # Sum of payments made to supplier
+      #       :balance           => BigDecimal(...)   # sales - purchases - sale_receipts + purchase_payments
+      #     },
+      #     :USD => {                                 # Another block as above, if the account uses
+      #       ...                                     # multiple currencies
+      #   }}
+      #
+      # The <tt>:balance</tt> fields indicate any outstanding money owed on the account: the value is
+      # positive if they owe you money, and negative if you owe them money.
+      def account_summary(self_id, other_id)
+        info = ledger_item_class_info
+        conditions = {info.method(:sender_id)    => [self_id, other_id],
+                      info.method(:recipient_id) => [self_id, other_id]}
+
+        with_scope :find => {:conditions => conditions} do
+          summaries = account_summaries(self_id)
+          summaries[other_id] || {}
+        end
+      end
+    
+      # Returns a summary account status for all customers or suppliers with which a particular party
+      # has dealings. Takes into account all +closed+ invoices/credit notes and all +cleared+ payments
+      # which have +self_id+ as their +sender_id+ or +recipient_id+. Returns a hash whose keys are the
+      # other party of each account (i.e. the value of +sender_id+ or +recipient_id+ which is not
+      # +self_id+, as an integer), and whose values are again hashes, of the same form as returned by
+      # +account_summary+:
+      #
+      #   LedgerItem.account_summaries(1)
+      #     # => { 2 => { :USD => { :sales => ... }, :EUR => { :sales => ... } },
+      #     #      3 => { :EUR => { :sales => ... } } }
+      #
+      # If you want to further restrict the ledger items taken into account in this calculation (e.g.
+      # include only data from a particular quarter) you can call this method within an ActiveRecord
+      # scope:
+      #
+      #   q3_2008 = ['issue_date >= ? AND issue_date < ?', DateTime.parse('2008-07-01'), DateTime.parse('2008-10-01')]
+      #   LedgerItem.scoped(:conditions => q3_2008).account_summaries(1)
+      #
+      def account_summaries(self_id)
+        info = ledger_item_class_info
+        ext = Invoicing::ConnectionAdapterExt
+        scope = scope(:find)
+        
+        debit_classes  = select_matching_subclasses(:debit_when_sent_by_self, true,  self.table_name, self.inheritance_column).map{|c| c.name}
+        credit_classes = select_matching_subclasses(:debit_when_sent_by_self, false, self.table_name, self.inheritance_column).map{|c| c.name}
+        debit_when_sent      = merge_conditions({info.method(:sender_id)    => self_id, info.method(:type) => debit_classes})
+        debit_when_received  = merge_conditions({info.method(:recipient_id) => self_id, info.method(:type) => credit_classes})
+        credit_when_sent     = merge_conditions({info.method(:sender_id)    => self_id, info.method(:type) => credit_classes})
+        credit_when_received = merge_conditions({info.method(:recipient_id) => self_id, info.method(:type) => debit_classes})
+
+        cols = {}
+        [:total_amount, :sender_id, :recipient_id, :status, :currency].each do |col|
+          cols[col] = connection.quote_column_name(info.method(col))
+        end
+        
+        sender_is_self    = merge_conditions({info.method(:sender_id)    => self_id})
+        recipient_is_self = merge_conditions({info.method(:recipient_id) => self_id})
+        other_id_column = ext.conditional_function(sender_is_self, cols[:recipient_id], cols[:sender_id])
+        filter_conditions = "#{cols[:status]} IN ('closed','cleared') AND (#{sender_is_self} OR #{recipient_is_self})"
+        
+        
+
+        sql = "SELECT #{other_id_column} AS other_id, #{cols[:currency]} AS currency, " + 
+          "SUM(#{ext.conditional_function(debit_when_sent,      cols[:total_amount], 0)}) AS sales, " +
+          "SUM(#{ext.conditional_function(debit_when_received,  cols[:total_amount], 0)}) AS purchase_payments, " +
+          "SUM(#{ext.conditional_function(credit_when_sent,     cols[:total_amount], 0)}) AS sale_receipts, " +
+          "SUM(#{ext.conditional_function(credit_when_received, cols[:total_amount], 0)}) AS purchases " +
+          "FROM #{(scope && scope[:from]) || quoted_table_name} "
+        
+        # Structure borrowed from ActiveRecord::Base.construct_finder_sql
+        add_joins!(sql, nil, scope)
+        add_conditions!(sql, filter_conditions, scope)
+        
+        sql << " GROUP BY other_id, currency"
+
+        add_order!(sql, nil, scope)
+        add_limit!(sql, {}, scope)
+        add_lock!(sql, {}, scope)
+        
+        rows = connection.select_all(sql)
+
+        results = {}
+        rows.each do |row|
+          row.symbolize_keys!
+          other_id = row[:other_id].to_i
+          currency = row[:currency].to_sym
+          summary = {:balance => BigDecimal('0')}
+          
+          {:sales => 1, :purchases => -1, :sale_receipts => -1, :purchase_payments => 1}.each_pair do |field, factor|
+            summary[field] = BigDecimal(row[field])
+            summary[:balance] += BigDecimal(factor.to_s) * summary[field]
+          end
+          
+          results[other_id] ||= {}
+          results[other_id][currency] = summary
+        end
+        
+        results
+      end
+    end
+    
+    
+    # Stores state in the ActiveRecord class object
+    class ClassInfo < Invoicing::ClassInfo::Base #:nodoc:
+      attr_reader :subtype, :uuid_generator
+      
+      def initialize(model_class, previous_info, args)
+        super
+        @subtype = all_options[:subtype]
+        
+        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 # module LedgerItem
+end