Build Status

Nusii

Ruby library for the Nusii API

Table of contents

Installation

To get the latest stable, add this to your Gemfile:

gem 'nusii'

To get the latest code, add this:

gem 'nusii', git: https://github.com/Nusii/nusii-ruby

And then execute:

$ bundle

Or install it yourself as:

$ gem install nusii

Setup

The only thing you need to do is add you API KEY:

require 'nusii-ruby'

Nusii.setup(:api_key => 'YOUR_API_KEY', :user_agent => 'your_user_agent')

Example usage

Listing resources

Use .list to retrieve a list of a resource

> Nusii::Client.list
=> #<Nusii::ResponseObject:0x007fadfb6d8ac0
 @meta={"current_page"=>1, "next_page"=>2, "prev_page"=>nil, "total_pages"=>2, "total_count"=>29},
 @resource_class=Nusii::Client,
 @resources=
  [#<Nusii::Client:0x007fadfb6eb468
    @currency="USD",
    @email="[email protected]",
    @full_name="Martin",
    @id=35843,
    @locale="en",
    @name="Martin",
    @pdf_page_size="A4">,
    ... ]

You can also pass options such as page or per:

> Nusii::Client.list(:per => 2, :page => 4)
=> #<Nusii::ResponseObject:0x007fadfb530c40
 @meta={"current_page"=>4, "next_page"=>5, "prev_page"=>3, "total_pages"=>15, "total_count"=>29},
 @resource_class=Nusii::Client,
 @resources=
  [#<Nusii::Client:0x007fadfb5313c0
    @currency="USD",
    @email="[email protected]",
    @full_name="Victor",
    @id=35835,
    @locale="es",
    @name="Victor",
    @pdf_page_size="A4">,
   #<Nusii::Client:0x007fadfb530e20
    @currency="EUR",
    @email="[email protected]",
    @full_name="Althea",
    @id=35834,
    @locale="en",
    @name="Althea",
    @pdf_page_size="A4">]>

Any ResponseObject instance also has the methods next_page and prev_page which will automatically make the requests based on the current search.

> response = Nusii::Client.list(:per => 4, :page => 2)
=> #<Nusii::ResponseObject:0x007fadfb0bd028
 @meta={"current_page"=>2, "next_page"=>3, "prev_page"=>1, "total_pages"=>8, "total_count"=>29},
 @resource_class=Nusii::Client,
 @resources= [...]

> response.prev_page
=> #<Nusii::ResponseObject:0x007f8df2c3b518
 @meta={"current_page"=>1, "next_page"=>2, "prev_page"=>nil, "total_pages"=>8, "total_count"=>29},
 @resource_class=Nusii::Client,
 @resources=[...]

Nusii::ListItem has also a method called .list_by_section that accepts a section_id as the first argument and retrieves ListItems under that section_id

Getting a single resource

Use .get to retrieve a single resource

> Nusii::Section.get 309405
=> #<Nusii::Section:0x007f8df3020778
 @id=309405,
 @body=
  "<p>We are a web design studio with offices in Madrid and Barcelona and we're lucky enough to work with people from all over the world./p>",
 @currency="EUR",
 @include_total=false,
 @name="Introduction",
 ...">

Creating and updating resources

You can create a resource with the class method .create by passing a hash of arguments:

> Nusii::Client.create({:name => 'Laura Palmer', :email => '[email protected]'})
=> #<Nusii::Client:0x007f8df2b6aa58
 @currency="USD",
 @email="[email protected]",
 @full_name="Laura Palmer",
 @id=35947,
 @locale="en",
 @name="Laura Palmer",
 @pdf_page_size="A4">

You can also create them by using #save on a new object:

client = Nusii::Client.new({:name => 'Laura Palmer', :email => '[email protected]'})
=> #<Nusii::Client:0x007f8df2b226e0 @email="[email protected]", @name="Laura Palmer">
> client.save
=> #<Nusii::Client:0x007f8df2abacc0
 @currency="USD",
 @email="[email protected]",
 @full_name="Laura Palmer",
 @id=35948,
 @locale="en",
 @name="Laura Palmer",
 @pdf_page_size="A4">

Any resource with a valid id value can be updated with the same method, #save.

> client.name = 'Sheryl Lee'
=> "Sheryl Lee"
> client.save
=> #<Nusii::Client:0x007f8df21521b0
 @currency="USD",
 @email="[email protected]",
 @full_name="Sheryl Lee",
 @id=35949,
 @locale="en",
 @name="Sheryl Lee",
 @pdf_page_size="A4">

Deleting resources

Just as happens with creation, a resource can be deleted by a class method .destroy passign a valid id or with #destroy on a instance.

> Nusii::WebhookEndpoint.destroy(54)
=> true

> webhook = Nusii::WebhookEndpoint.get(55)
=> #<Nusii::WebhookEndpoint:0x007f8df2302a28 @events=["proposal_updated"], @id=55, @target_url="http://example.com">
> webhook.destroy
=> true

Sending a proposal

With any Proposal object you can use the method #send_proposal. You need to pass at least the email of the client you want the existing proposal sent to. Please refer to the API for more information.

> proposal.send_proposal(:email => '[email protected]')
=> {"status"=>"pending", "sent_at"=>"2017-12-11T12:37:12.593Z", "sent_at_in_ms"=>1512995832000, "sender_id"=>nil, "sender_name"=>nil}

Retrieving account information

Use Account.me to get the information from your account

> Nusii::Account.me
=> #<Nusii::Account:0x007fb042f30350
 @address="Calle Mayor, 23",
 @city="Madrid",
 @country="Spain",
 @country_name="Spain",
 @currency="EUR",
 @email="[email protected]",
 @id=44,
 @name="Michael Account",
 @postcode="28017",
 @subdomain="michael",
 @telephone="123456789",
 @web="nusii.com">

Rate limiting

There is a rate limit in Nusii API of 100 requests every 30 seconds. After every request, a class variable in Nusii will get updated so you can check if you are reaching the limit

> Nusii.rate_limit_remaining
=> 98
> Nusii::Account.me
=> #<Nusii::Account:0x007f8df20fa028 ...>
> Nusii.rate_limit_remaining
=> 97

There's another variable called rate_limit_retry_after that will store the amount of time, in seconds, that you have to wait if you have reached the limit.

Available methods by resource

Account

  • Nusii::Account.me

Clients

  • Nusii::Client.list
  • Nusii::Client.get
  • Nusii::Client.create
  • Nusii::Client#save
  • Nusii::Client.destroy
  • Nusii::Client#destroy

Sections

  • Nusii::Section.list
  • Nusii::Section.get
  • Nusii::Section.create
  • Nusii::Section#save
  • Nusii::Section.destroy
  • Nusii::Section#destroy

Line Items

  • Nusii::LineItem.list
  • Nusii::LineItem.list_by_section
  • Nusii::LineItem.create_with_section
  • Nusii::LineItem#save
  • Nusii::LineItem.destroy
  • Nusii::LineItem#destroy

Proposals

  • Nusii::Proposal.list
  • Nusii::Proposal.get
  • Nusii::Proposal.create
  • Nusii::Proposal#save
  • Nusii::Proposal.destroy
  • Nusii::Proposal#destroy
  • Nusii::Proposal#send_proposal

Proposal Activities

  • Nusii::Proposal.list
  • Nusii::Proposal.get

Webhook Enpoints

  • Nusii::WebhookEndpoint.list
  • Nusii::WebhookEndpoint.get
  • Nusii::WebhookEndpoint.create
  • Nusii::WebhookEndpoint#save
  • Nusii::WebhookEndpoint.destroy
  • Nusii::WebhookEndpoint#destroy

Contributing

If you want to contribute, please follow these easy steps:

  1. Fork it ( http://github.com/nusii/nusii-ruby/fork )
  2. Create your feature branch (git checkout -b improving-something)
  3. Commit your changes (git commit -am 'Let's improve this!')
  4. Push to the branch (git push origin improving-something)
  5. Create new Pull Request

License

Released under the MIT License.