= freeagent_api

Simple ActiveResource Ruby wrapper for the Freeagent Central API (http://www.freeagentcentral.com/developers/freeagent-api).

This supports all GET, POST, PUT and DELETE ActiveResource calls for the following API resources:

* Company
* Contacts
* Projects
* Tasks
* Invoices
* Invoice Items
* Timeslips
* Users

At the moment, the following API resources are NOT supported (although is being worked on):

* Expenses
* Attachments

Feel free to clone, fork and add tests.

== Installation

To install as a Gem, just run:

  $ sudo gem install freeagent_api -s http://gemcutter.org

Please note: version 0.2 is significantly different from 0.1 so if you are upgrading from the early development version please re-familiarise yourself with the documentation.

== Usage

=== Authentication

  Freeagent.authenticate({
    :domain => 'yourdomain.freeagentcentral.com',
    :username => 'your@login.com',
    :password => 'your_password'})

=== Company

<b>Timelines</b>

  @invoice_timeline = Company.invoice_timeline
  @tax_timeline = Company.tax_timeline

=== Contacts

<b>Find contacts</b>

  @contacts = Contact.find :all         # returns all contacts
  @contact = Contact.find id            # returns specific contact

<b>Create contact</b>

  # Required attributes
  #   :first_name
  #   :last_name
  
  @contact = Contact.new params
  @contact.save

<b>Update contact</b>

  @contact.first_name = 'Joe'
  @contact.save

<b>Delete contact</b>

  Contact.delete id
  # or
  @contact.destroy

=== Projects

<b>Find projects</b>

  @projects = Project.find :all         # returns all projects
  @project = Project.find id            # returns specific project

<b>Create project</b>

  # Required attribues
  #   :contact_id
  #   :name
  #   :payment_term_in_days
  #   :billing_basis                    # must be 1, 7, 7.5, or 8
  #   :budget_units                     # must be Hours, Days, or Monetary
  #   :status                           # must be Active or Completed
  
  @project = Project.new params
  @project.save

<b>Update project</b>

  @project.name = 'Web design project'
  @project.save

<b>Delete project</b>

  Project.delete id
  # or
  @project.destroy

<b>Nested resources</b>

  @invoices = @project.invoices
  @timeslips = @project.timeslips

=== Tasks

<b>Find tasks</b>

  @tasks = Task.find :all               # returns all tasks
  @task = Task.find id                  # returns specific task

<b>Create task</b>

  # Required attributes
  #   :name
  
  @task = Task.new params
  @task.save

<b>Update task</b>

  @task.name = 'Create wireframes'
  @task.save

<b>Delete task</b>

  Task.delete id
  # or
  @task.destroy

=== Invoices

<b>Find Invoices</b>

  @invoices = Invoice.find :all         # returns all invoices
  @invoice = Invoice.find id            # returns specific invoice

<b>Create invoice</b>

  # Required attributes
  #   :contact_id
  #   :project_id
  #   :dated_on
  #   :reference
  #   :status
  
  @invoice = Invoice.new params
  @invoice.save

<b>Update invoice</b>

  @invoice.status = 'Sent'
  @invoice.save

<b>Delete invoice</b>

  Invoice.delete id
  # or
  @invoice.destroy

<b>Changing status</b>

  @invoice.mark_as_draft
  @invoice.mark_as_sent
  @invoice.mark_as_cancelled

=== Invoice items

<b>Find invoice items</b>

  @invoice_items = InvoiceItem.find :all  # returns all invoice items
  @invoice_item = InvoiceItem.find id     # returns specific invoice item

<b>Create invoice item</b>

  # Required attributes
  #   :item_type                        # must be Hours, Days, Months, Years, Products, Services, Expenses, Discount, Credit, Comment
  #   :description
  #   :quantity
  #   :price
  #   :sales_tax_rate
  
  @invoice_item = InvoiceItem.new params
  @invoice_item.save

<b>Update invoice item</b>

  @invoice_item.name = 'Create wireframes'
  @invoice_item.save

<b>Delete invoice item</b>

  InvoiceItem.delete id
  # or
  @invoice_item.destroy

=== Timeslips

<b>Find timeslips</b>

  @timeslips = Timeslip.find :all, :params => {:from => '2009-10-01', :to => '2009-10-30'}
                                        # returns all timeslips (:from and :to dates required)
  @timeslip = Timeslip.find id          # returns specific timeslip

<b>Create timeslip</b>

  # Required attributes
  #   :user_id
  #   :hours
  #   :dated_on
  #   :task_id OR :new_task
  
  @timeslip = Timeslip.new params
  @timeslip.save

<b>Update timeslip</b>

  @timeslip.hours = '3.5'
  @timeslip.save

<b>Delete timeslip</b>

  Timeslip.delete id
  # or
  @timeslip.destroy

=== Users

<b>Find users</b>

  @users = User.find :all       # returns all users
  @user = User.find id          # returns specific user
  @user = User.find_by_email email

<b>Create user</b>

  # Required attributes
  #   :first_name
  #   :last_name
  #   :email
  #   :role                     # must be Owner, Director, Partner, Company Secretary, Employee, Shareholder, or Accountant
  #   :password
  #   :password_confirmation
  
  @user = User.new params
  @user.save

<b>Update user</b>

  @user.first_name = 'Joe Bloggs'
  @user.save

<b>Delete user</b>

  User.delete id
  # or
  @user.destroy

== Author & Contributors
 
* Aaron Russell - (www.aaronrussell.co.uk)
* Alex Comans - (www.alexcoomans.com)

== Copyright

Copyright (c) 2009-2010 Aaron Russell. See LICENSE for details.