pinboard.js v1.0.2
pinboard.js
Library for talking to the Pinboard API
This was written as part of firefox-pinboard
to communicate with Pinboard. We chose to write pinboard.js
to allow for handling of errors that previous libraries did not expose (e.g. ECONNREFUSED
).
Getting Started
npm
Install the module with: npm install pinboard.js
// Create a client
// API token can be found at: https://pinboard.in/settings/password
var Pinboard = require('pinboard.js');
var pinboard = new Pinboard({
auth: {
type: 'token',
username: 'your-username',
token: 'your-token'
}
});
// Find out when we last updated a post
pinboard.postsUpdate({
format: 'json'
}, console.log); // {"update_time":"2015-02-13T09:08:22Z"}
bower
Install the module with: bower install pinboard.js
Once installed, add it to your HTML and access it via window.Pinboard
.
<script src="bower_components/pinboard.js/dist/pinboard.min.js"></script>
<script>
window.pinboard = new window.Pinboard({auth: {/*...*/}); // Our Pinboard client
</script>
Vanilla
If you are not using a package manager, download the latest script at:
https://raw.githubusercontent.com/twolfson/pinboard.js/master/dist/pinboard.min.js
Then, add it to your HTML and access it via window.Pinboard
.
<script src="pinboard.min.js"></script>
<script>
window.pinboard = new window.Pinboard({auth: {/*...*/}); // Our Pinboard client
</script>
Documentation
pinboard.js
exposes Pinboard
as its module.exports
.
new Pinboard(params)
Creates a new Pinboard client
- params
Object
- Container for parameters- auth
Object
- Container for authentication info- type
String
- Type of authentication to use- This can be
http
(username + password) ortoken
(username + API token) - By default, we use
token
based authentication
- This can be
- username
String
- Username to authenticate with - password
String
- Password to use forhttp
authentication- If you are performing
token
auth, then this is not required - This is the password you use to log in to Pinboard
- If you are performing
- token
String
- Password to use fortoken
authentication- If you are performing
http
auth, then this is not required - This is the second half of the token provided on https://pinboard.in/settings/password
- For example, if the page lists "twolfson:abcd", then your token is "abcd"
- If you are performing
- type
- auth
- url
Object
- URL parameters to use instead of normal Pinboard url- This should be in the format expected by
node's url.format
method (e.g.protocol
,hostname
,pathname
) - By default, this is
{protocol: 'https:', hostname: 'api.pinboard.in', pathname: '/v1'}
- This should be in the format expected by
Using token auth:
// API token can be found at: https://pinboard.in/settings/password
new Pinboard({
auth: {
type: 'token',
username: 'your-username',
token: 'your-token'
}
});
Using http auth:
// Credentials are the same you use to log in with
new Pinboard({
auth: {
type: 'http',
username: 'your-username',
password: 'your-password'
}
});
Methods
All methods are light wrappers around the Pinboard API.
The function signature will consistently be:
(options, cb)
- options
Object
- Parameters to pass through to Pinboard API- For example, if the endpoint says it requires
url
, then you must pass in something like{url: 'http://mywebsite.com/'}
- format
String
- Format to output content as- This can be
json
orxml
- We will not parse the output content (e.g. JSON will be a
String
) - By default, Pinboard will return
xml
- This can be
- For example, if the endpoint says it requires
- cb
Function
- Response handlercb
should have a signature of(err, res, body)
- We leverage
request
so the format of each item is the same
- We leverage
- err
Error|null
- If an error occurred, then this will be it- For example, if the server is down, then this can be an
ECONNREFUSED
error
- For example, if the server is down, then this can be an
- res
Object
- Response message from server- statusCode
Number
- Status code for response (e.g.200
for success) - headers
Object
- Container for response headers - Further information can be found in http://nodejs.org/api/http.html#http_http_incomingmessage
- statusCode
- body
String
- Body from response- If
json
was requested viaformat
, then this will be JSON. Otherwise, it will be XML.
- If
Example request for JSON:
pinboard.postsUpdate({
url: 'http://pinboard.in/',
description: 'Great bookmarking site',
format: 'json'
}, console.log); // {"result_code":"done"}
pinboard.postsUpdate(options, cb)
Returns the most recent time a bookmark was added, updated, or deleted
https://pinboard.in/api#posts_update
- See Methods for
options
andcb
documentation
postsAdd(options, cb)
Add a new bookmark
https://pinboard.in/api#posts_add
- See Methods for
options
andcb
documentation
postsDelete(options, cb)
Delete a given bookmark
https://pinboard.in/api#posts_delete
- See Methods for
options
andcb
documentation
postsGet(options, cb)
Return matching posts for a given search
https://pinboard.in/api#posts_get
- See Methods for
options
andcb
documentation
postsRecent(options, cb)
Returns your most recent posts filtered by tag
https://pinboard.in/api#posts_recent
This is endpoint is rate limited to 1 request per 1 minute.
- See Methods for
options
andcb
documentation
postsDates(options, cb)
Returns a listing of posts per date
https://pinboard.in/api#posts_dates
- See Methods for
options
andcb
documentation
postsAll(options, cb)
Return all bookmark in your account
https://pinboard.in/api#posts_all
This is endpoint is rate limited to 1 request per 5 minutes.
- See Methods for
options
andcb
documentation
postsSuggest(options, cb)
Return popular and recommended tags for a URL
https://pinboard.in/api#posts_suggest
- See Methods for
options
andcb
documentation
tagsGet(options, cb)
Return object mapping tags to usage counts
https://pinboard.in/api/#tags_get
- See Methods for
options
andcb
documentation
tagsDelete(options, cb)
Delete a given tag
https://pinboard.in/api/#tags_delete
- See Methods for
options
andcb
documentation
tagsRename(options, cb)
Rename an existing tag or merge it into another tag
https://pinboard.in/api/#tags_rename
- See Methods for
options
andcb
documentation
userSecret(options, cb)
Returns your secret RSS key for viewing private feeds
https://pinboard.in/api/#user_secret
- See Methods for
options
andcb
documentation
userApiToken(options, cb)
Returns your API token
https://pinboard.in/api/#user_api_token
- See Methods for
options
andcb
documentation
notesList(options, cb)
Returns a list of your notes
No good link anchor provided.
- See Methods for
options
andcb
documentation
notesId(options, cb)
Returns a detailed information about a specific note
No good link anchor provided.
- See Methods for
options
andcb
documentation - This method has an additional parameter for
options
as it is inconsistent with the rest of the API- id
String
- 20 character hash to access note by
- id
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint
and test via npm test
.
Testing
We currently require an active Pinboard account for testing. Please output your auth
parameters for the Pinboard
constructor into test/test-credentials.json
before running the tests. These are .gitignore'd
and should present no issue.
{
"type": "token",
"username": "twolfson",
"token": "abcdef..."
}
Donating
Support this project and others by twolfson via gratipay.
Unlicense
As of Jan 23 2015, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.