Project

nusii

0.0
Low commit activity in last 3 years
Ruby library for the Nusii API.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Project Readme

Build Status

Nusii

Ruby library for the Nusii API

Table of contents

  • Installation
  • Setup
  • Example usage
  • Available methods by resource
  • Contributing
  • Usage

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="martin@madeupcompany.com",
    @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="victor@madeupcompany.com",
    @full_name="Victor",
    @id=35835,
    @locale="es",
    @name="Victor",
    @pdf_page_size="A4">,
   #<Nusii::Client:0x007fadfb530e20
    @currency="EUR",
    @email="altheasmith@madeupcompany.com",
    @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 => 'laura.palmer@tphs.com'})
=> #<Nusii::Client:0x007f8df2b6aa58
 @currency="USD",
 @email="laura.palmer@tphs.com",
 @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 => 'laura.palmer@tphs.com'})
=> #<Nusii::Client:0x007f8df2b226e0 @email="laura.palmer@tphs.com", @name="Laura Palmer">
> client.save
=> #<Nusii::Client:0x007f8df2abacc0
 @currency="USD",
 @email="laura.palmer@tphs.com",
 @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="laura.palmer@tphs.com",
 @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 => 'lucas.tazmily@myclient.com')
=> {"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="michael@test.com",
 @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.