subledger 0.7.7

data/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.rbx
+.bundle/
+coverage/
+tmp/
+public
+vendor/
+Gemfile.lock
+subledger-*.gem

data/LICENSE.txt

@@ -0,0 +1,12 @@
+Copyright (c) 2014, Subledger, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,136 @@
+[![Build Status](https://magnum.travis-ci.com/boocx2/subledger.png?token=xpzDphMqDV2co7CrgGkL&branch=reporting)](https://magnum.travis-ci.com/boocx2/subledger)
+
+Signup:
+
+    gem install subledger
+
+    subledger
+
+    Welcome to Subledger, the world's first in-app accounting API!
+
+    To stop this script at any time simply press control-C.
+
+    We require your email address for verification.
+
+    Please enter your email address:
+    > your@email.com
+
+      creating key...created!
+
+      Your key: Gid1vE0lStRnPNCx9GFmL5
+
+      You *must* keep it 100% secure, or your data may be accessed by others.
+
+    Would you like your key written into ~/.subledger for you?
+    This prevents the need for you to enter it or put it in source code.
+    > n
+
+      OK, please store your key and secret securely.
+
+    > y
+
+      Your key has been written to ~/.subledger
+
+    Your key is not yet ready to use, it must be verified via email.
+
+    Please enter the verification code we sent you via email:
+    > V6XxRwP5j9ldaeDjOpbkv7
+
+      Verifying key...verified!
+
+      Sorry, that verification code does not match your key. Please try again.
+
+    Next, we'll create an organization.
+
+    The organization name will be present in URLs, and must be unique.
+
+    What organization name would you like to use?
+    > subledger
+
+      creating organization "subledger"...created!
+
+      Your key has been granted access to your new organization.
+
+    Next we'll create a book in the subledger organization to create accounts in.
+
+    A book tracks the state of one dimension of your business.
+
+    The most common book tracks the state of currency in your business.
+
+    What would you like to name your book? We'd suggest Dollars, Euros, Yen, etc.
+    > USD
+
+      creating book "USD"...created!
+
+    Would you like to create a very basic set of accounting accounts?
+    > n
+
+    > y
+
+    creating account "1000 Assets"...created!
+    creating account "2000 Liabilities"...created!
+    creating account "3000 Equity"...created!
+    creating account "4000 Income"...created!
+    creating account "5000 Cost of goods sold"...created!
+    creating account "6000 Expenses"...created!
+
+    Would you like to become virtually wealthy?
+    > n
+
+      Ok, just remember: early to bed, early to rise, makes a man healthy, wealthy and wise! :-)
+
+    > y
+
+      posting opening balances...posted!
+
+    Congratulations, you've successfully setup Subledger!
+
+    Your private and secure API explorer now exists at:
+
+      https://api.subledger.com/
+
+    You'll need to enter your key_id and secret where indicated.
+
+Post Signup:
+
+  Gemfile:
+
+      gem install subledger
+
+  Client setup:
+
+      subledger = Subledger.new :key_id  => '',
+                                :secret  => '',
+                                :org_id  => '',
+                                :book_id => ''
+
+  Basic accounting objects:
+
+      debit  = subledger.debit  '1'
+      credit = subledger.credit '1'
+      zero   = subledger.zero   '0'
+
+      debit + credit          == zero
+      debit + debit  + credit == debit
+      debit + credit + credit == credit
+
+      book = subject.books.create :description => 'description of book', # required
+                                  :reference   => 'http://url.of.choice' # optional, must be a URL if present
+
+      book = subledger.books.read :id => book.id
+
+      book.update :description => '',
+                  :reference   => ''
+
+      book.archive
+      book.activate
+
+      subledger.books.collect :state       => :active|:archived,
+                              :action      => :before|:ending|:starting|:after,
+                              :description => 'description',
+                              :limit       => 25
+
+      subledger.books.collect :state  => :active|:archived,
+                              :action => :preceding|:following,
+                              :id     => another_book_in_this_org.id,
+                              :limit  => 25

data/Rakefile

@@ -0,0 +1,5 @@
+# DO NOT EDIT THIS FILE! (Create new task(s) using lib/tasks/*.rake convention
+
+Dir[ File.expand_path( __FILE__ + '/..' ) + '/lib/tasks/*.rake' ].each do |f|
+  load f
+end

data/bin/subledger

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+echo "Welcome to the Subledger CLI!"
+echo
+
+irb -Ilib -rsubledger

data/lib/subledger/actor.rb

@@ -0,0 +1,32 @@
+require 'celluloid/autostart'
+
+Celluloid.logger = Subledger::LOG
+
+module Subledger
+  class Actor
+    include Celluloid
+
+    private
+
+    def worker type
+      worker_actor = nil
+
+      while ( worker_actor = Celluloid::Actor[ type ] ).nil?
+        sleep 0.1
+      end
+
+      worker_actor
+    end
+
+    CLIENT_HASH = 'client_hash'
+    ORG_ID      = 'org_id'
+    BOOK_ID     = 'book_id'
+
+    def client_for args
+      client_hash = args[CLIENT_HASH]
+
+      Subledger.new :org_id  => client_hash[ORG_ID],
+                    :book_id => client_hash[BOOK_ID]
+    end
+  end
+end

data/lib/subledger/collection_name.rb

@@ -0,0 +1,25 @@
+module Subledger
+  module CollectionName
+    def self.without_state args
+      anchor = args[:anchor]
+      klass  = anchor.class
+
+      if klass == Domain::PostedLine and not anchor.account.nil?
+        :account_lines
+      else
+        klass.root_klass.collection_name
+      end
+    end
+
+    def self.with_state args
+      klass = args[:klass]
+      state = args[:state]
+
+      if klass == Domain::PostedLine and not args[:account].nil?
+        :account_lines
+      else
+        "#{state}_#{klass.root_klass.collection_name}".to_sym
+      end
+    end
+  end
+end

data/lib/subledger/domain/account.rb

@@ -0,0 +1,168 @@
+module Subledger
+  module Domain
+    class AccountError < Error; end
+
+    class Account
+
+      include Domain
+
+      include Roles::Attributable
+      include Roles::Describable
+      include Roles::Identifiable
+      include Roles::Storable
+      include Roles::Versionable
+
+      include Roles::Creatable
+      include Roles::Readable
+      include Roles::Updatable
+
+      include Roles::Collectable
+
+      include Roles::Activatable
+      include Roles::Archivable
+
+      include Roles::Restable
+
+      attr_reader   :book
+      attr_accessor :normal_balance
+
+      def self.post_keys
+        [ :description, :reference, :normal_balance ]
+      end
+
+      def self.patch_keys
+        [ :id, :description, :reference, :normal_balance, :version ]
+      end
+
+      def self.root_klass
+        Account
+      end
+
+      def self.sub_klasses
+        [ active_klass, archived_klass ]
+      end
+
+      def self.active_klass
+        ActiveAccount
+      end
+
+      def self.archived_klass
+        ArchivedAccount
+      end
+
+      def self.first_and_last_line args
+        store  = args[:store]
+        client = args[:client]
+
+        id = args[:id]
+
+        if id.nil?
+          raise AccountError, 'cannot get first and last lines without an :id'
+        end
+
+        args.merge! :account => client.accounts( :id => id )
+
+        store.first_and_last_line args
+      end
+
+      def initialize args
+        describable args
+        identifiable args
+        storable args
+        versionable args
+
+        @book           = args[:book]
+        @normal_balance = args[:normal_balance]
+      end
+
+      def line args
+        client.posted_lines( args.merge! :account => self )
+      end
+
+      def lines args={ }, &block
+        args.merge! :action       => args[:action]       || :ending,
+                    :state        => args[:state]        || :posted,
+                    :effective_at => args[:effective_at] || Time.now.utc,
+                    :account      => self
+
+        client.account_lines.collect args, &block
+      end
+
+      def balance args
+        at = args[:at]
+
+        unless at.kind_of? Time
+          raise AccountError, ':at must be a Time'
+        end
+
+        store.account_balance :store   => store,
+                              :client  => client,
+                              :account => self,
+                              :at      => at.utc
+      end
+
+      def first_and_last_line
+        client.accounts.first_and_last_line :id => self.id
+      end
+
+      class Entity < Grape::Entity
+        root 'accounts', 'account'
+
+        expose :id,             :documentation => { :type => 'string',  :desc => 'account ID' }
+
+        expose :book,           :format_with   => :id,
+                                :documentation => { :type => 'string',  :desc => 'book ID' }
+
+        expose :description,    :documentation => { :type => 'string',  :desc => 'description' }
+
+        expose :reference,      :documentation => { :type => 'string',  :desc => 'reference URI' }
+
+        expose :normal_balance, :format_with   => :normal_balance,
+                                :documentation => { :type => 'string',  :desc => 'normal balance type' }
+
+        expose :version,        :documentation => { :type => 'integer', :desc => 'version' }
+      end
+
+      private
+
+      ACCEPTABLE_NORMAL_BALANCES = [ Debit, Credit ]
+
+      def self.raise_unless_creatable args
+
+        book = args[:book]
+
+        if book.nil? or not book.kind_of? Book
+          raise AccountError, ':book is required and must be a Book'
+        elsif UUID.invalid? book.id
+          raise AccountError, ':book must have a valid :id'
+        end
+
+        normal_balance = args[:normal_balance]
+
+        if normal_balance.nil? or not ACCEPTABLE_NORMAL_BALANCES.include? normal_balance
+          raise AccountError, ":normal_balance is required and must be one of #{ACCEPTABLE_NORMAL_BALANCES.join(', ')}"
+        end
+      end
+    end
+
+    class ArchivedAccount < Account
+      class Entity < Account::Entity
+        root 'archived_accounts', 'archived_account'
+      end
+
+      def self.sub_klasses
+        [ archived_klass ]
+      end
+    end
+
+    class ActiveAccount < Account
+      class Entity < Account::Entity
+        root 'active_accounts', 'active_account'
+      end
+
+      def self.sub_klasses
+        [ active_klass ]
+      end
+    end
+  end
+end

data/lib/subledger/domain/balance.rb

@@ -0,0 +1,102 @@
+module Subledger
+  module Domain
+    class BalanceError < Error; end
+
+    class Balance
+
+      # Implements Valuable directly: #value, #amount, #+ and #==
+      # Implements Attributable directly: #attributes
+
+      include Domain
+
+      include Roles::Restable
+
+      def initialize args={ :debit_value => Zero.new, :credit_value => Zero.new }
+        if args[:debit_value].nil? or args[:credit_value].nil?
+          raise BalanceError, ':debit_value and :credit_value required'
+        end
+
+        @debit_amount  = args[:debit_value].amount
+        @credit_amount = args[:credit_value].amount
+      end
+
+      def debit_value
+        debit_amount.zero? ? Zero.new : Debit.new( debit_amount )
+      end
+
+      def credit_value
+        credit_amount.zero? ? Zero.new : Credit.new( credit_amount )
+      end
+
+      def balanced?
+        value == Zero.new
+      end
+
+      def value
+        if debit_amount == credit_amount
+          Zero.new
+        elsif debit_amount > credit_amount
+          Debit.new( debit_amount - credit_amount )
+        else
+          Credit.new( credit_amount - debit_amount )
+        end
+      end
+
+      def amount
+        value.amount
+      end
+
+      def + other
+        klass = other.class
+
+        debit_amount  = @debit_amount
+        credit_amount = @credit_amount
+
+        if klass == Balance
+          debit_amount  += other.debit_value.amount
+          credit_amount += other.credit_value.amount
+        elsif klass == Debit
+          debit_amount += other.amount
+        elsif klass == Credit
+          credit_amount += other.amount
+        elsif klass == Zero
+          return self.dup
+        elsif other.kind_of? Line
+          return self + other.value
+        else
+          raise BalanceError, "cannot add #{other.class.name} to a Balance"
+        end
+
+        self.class.new :debit_value  => debit_amount.zero?  ? Zero.new : Debit.new(debit_amount),
+                       :credit_value => credit_amount.zero? ? Zero.new : Credit.new(credit_amount)
+      end
+
+      def == other
+        debit_value == other.debit_value and credit_value == other.credit_value
+      end
+
+      def attributes
+        { :debit_value  => debit_value,
+          :credit_value => credit_value,
+          :value        => value }
+      end
+
+      class Entity < Grape::Entity
+        root 'balances', 'balance'
+
+        expose :debit_value,  :format_with   => :value,
+                              :documentation => { :type => 'string',  :desc => 'Total debits' }
+
+        expose :credit_value, :format_with   => :value,
+                              :documentation => { :type => 'string',  :desc => 'Total credits' }
+
+        expose :value,        :format_with   => :value,
+                              :documentation => { :type => 'string',  :desc => 'Total combined debits and credits' }
+      end
+
+      private
+
+      attr_reader :debit_amount, :credit_amount
+    end
+  end
+end

data/lib/subledger/domain/book.rb

@@ -0,0 +1,111 @@
+module Subledger
+  module Domain
+    class BookError < Error; end
+
+    class Book
+
+      include Domain
+
+      include Roles::Attributable
+      include Roles::Describable
+      include Roles::Identifiable
+      include Roles::Storable
+      include Roles::Versionable
+
+      include Roles::Creatable
+      include Roles::Readable
+      include Roles::Updatable
+
+      include Roles::Collectable
+
+      include Roles::Activatable
+      include Roles::Archivable
+
+      include Roles::Restable
+
+      attr_reader :org
+
+      def self.post_keys
+        [ :org, :description, :reference ]
+      end
+
+      def self.patch_keys
+        # TODO should :id be in patch_keys?
+
+        [ :id, :description, :reference, :version ]
+      end
+
+      def self.root_klass
+        Book
+      end
+
+      def self.sub_klasses
+        [ active_klass, archived_klass ]
+      end
+
+      def self.active_klass
+        ActiveBook
+      end
+
+      def self.archived_klass
+        ArchivedBook
+      end
+
+      def initialize args
+        describable args
+        identifiable args
+        storable args
+        versionable args
+
+        @org  = args[:org]
+      end
+
+      class Entity < Grape::Entity
+        root 'books', 'book'
+
+        expose :id,          :documentation => { :type => 'string',  :desc => 'book ID' }
+
+        expose :org,         :format_with   => :id,
+                             :documentation => { :type => 'string',  :desc => 'org ID' }
+
+        expose :description, :documentation => { :type => 'string',  :desc => 'description' }
+
+        expose :reference,   :documentation => { :type => 'string',  :desc => 'reference URI' }
+
+        expose :version,     :documentation => { :type => 'integer', :desc => 'version' }
+      end
+
+      private
+
+      def self.raise_unless_creatable args
+        org = args[:org]
+
+        if org.nil? or not org.kind_of? Org
+          raise BookError, ':org is required and must be an Org'
+        elsif UUID.invalid? org.id
+          raise BookError, ':org must have a valid :id'
+        end
+      end
+    end
+
+    class ArchivedBook < Book
+      class Entity < Book::Entity
+        root 'archived_books', 'archived_book'
+      end
+
+      def self.sub_klasses
+        [ archived_klass ]
+      end
+    end
+
+    class ActiveBook < Book
+      class Entity < Book::Entity
+        root 'active_books', 'active_book'
+      end
+
+      def self.sub_klasses
+        [ active_klass ]
+      end
+    end
+  end
+end