Kippt

Kippt is a gem that provides a client library for using Kippt.com API.

Installation

Add this line to your application's Gemfile:

gem "kippt"

And then execute:

$ bundle

Or install it yourself as:

$ gem install kippt

Usage

Authentication

To be able to use the API you need to authenticated. There's two ways to authenticate:

With login credentials

client = Kippt::Client.new(username: "vesan", password: "s3cr3t")
# Methods called on `client` will use the passed credentials

With token

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
# Methods called on `client` will use the passed credentials

Or you can use the API unauthenticated:

client = Kippt::Client.new(unauthenticated: true)

Account

You can get the current authenticated user:

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
account = client.account
account.username #=> "vesan"
account = client.account(true) # includes the API token
account.api_token    #=> "2544d6bfddf5893ec8617"

Always use the API token instead of the password if possible because it's more secure.

Resources

Lists

Get all the lists:

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
lists = client.lists.fetch # Returns Kippt::ListCollection

Get single list:

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
list_id = 10
list = client.lists[list_id] # Returns Kippt::ListItem

Get single lists’s clips:

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
list_id = 10
list = client.lists[list_id].clips # Returns a Kippt::ClipCollection

# OR

list = Kippt::List.new({ id: list_id }, client)
list.clips # Returns a Kippt::ClipCollection

Clips

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
client.clips.fetch # Returns Kippt::ClipCollection

# Returns first page of clips for an URL
client.clips.fetch(url: "https://github.com/vesan/kippt")

# Returns first page of clips added in the last day
client.clips.fetch(since: Time.now.to_i - 86400)

Both ListCollection and ClipCollection are Enumerable.

Pagination

Lists and clips are paginated:

client = Kippt::Client.new(username: "vesan", token: "2544d6bfddf5893ec8617")
clips = client.clips.fetch

clips.total_count
clips.offset
clips.limit

You can get next and previous set of results:

clips.next_page? #=> true
clips.next_page # Returns new Kippt::ClipCollection
clips.previous_page? #=> true
clips.previous_page # Returns new Kippt::ClipCollection

Limit and offset can be controlled manually:

client.clips.fetch(limit: 25, offset: 50)

Search

Clips can be searched:

client.clips.search("kippt") #=> Returns Kippt::ClipCollection

Other available options are is\_starred: true and list: [list-id] like:

client.clips.search(q: "kippt", list: 5, is_starred: true)

Creating and updating resources

You can create new resources, here for example clips:

clip = client.clips.build
clip.url = "http://github.com"
clip.save #=> Returns boolean

If you are missing required fields #save will return false and you can use #errors to get the error messages returned by the API.

clip = client.clips.build
clip.save   #=> false
clip.errors #=> ["No url."]

Deleting resources

Deleting resources is done with #destroy:

clip_id = 1001
clip = client.clips[clip_id]
clip.destroy #=> true

Debugging

To get more information on what is going on under the covers, set DEBUG=true as environment variable or pass debug: true in the Kippt::Client options hash like:

client = Kippt::Client.new(unauthenticated: true, debug: true)

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Do your changes
4. Run the tests (rspec spec)
5. Commit your changes (git commit -am 'Added some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new Pull Request (https://github.com/vesan/kippt/pulls)