#fickr

So, the Flickr API is really full-featured but it does a few things that make it annoying to use:

• The auth system is currently in a state of flux between their previous non-standard system and the OAuth 1.0 standard, so documentation references to an "API key" aren't terribly clear.
• Cross-origin resource sharing (CORS) is not enabled, so making API requests from a browser is a pain in the ass.
• Their API and its documentation devote a lot of space to the social features of Flickr, which is fine but outside what I can only assume is the 95% use case for Flickr API integrations: displaying and uploading photos belonging to a single user.

fickr optimizes for that use case, and takes care of all the necessary bullshit for making as many API requests from the browser as possible despite the CORS limitation. If you only need Flickr access from the server, this is probably the wrong library to use, but if you want to access Flickr from the browser and keep the option of re-using some of that code on the server, flickr.js is just what you need.

##Usage

npm install fickr

NB. You'll need a consumer key and secret before you can try any of this.

To get a user key and secret (this part only works with Node.js due to CORS):

var fickr = require('fickr')

fickr.getAuthURL(
  <consumerKey>,    //developer key from Flickr
  <consumerSecret>, //...
  <callbackURL>,    //an http(s) URL to which the user will be directed
                    //after authenticating your app
  <callback>)       //callback function, receives single URL

For test purposes, you can run that in your Node.js REPL with console.log as the callback. In production you'll probably want the callback to re-direct the user to the URL provided. Either way, the URL goes to Flickr's OAuth permission page. If the user agrees to give read/write permissions to your app (all Flickr OAuth apps require it) they will be re-directed to the callback URL (the one that was passed to getAuthURL) with a query string containing values for an OAuth request token and a request verifier. Once you have those values:

fickr.getAccessToken(<requestToken>,<requestVerifier>,<callback>)

will return an object containing user data containing their OAuth credentials for your app (as well as their name, NSID, etc.) Those credentials will remain active until Flickr or the user decide to deactivate them, so if you store them you can save yourself from having to re-authenticate your users with Flickr every time.

In either the browser or the server, once you have a user's credentials, you can enable the rest of the library's functionality by calling fickr.init as follows:

fickr.init(<consumerKey>,<consumerSecret>,<userID>,<userKey>,<userSecret>)

Now, to access your user's Flickr photos on their behalf, fickr provides three simple read functions and one write (upload) functions:

• fickr.fetch(<callback>[,<page>]) calls flickr.people.getPhotos with the optional page number for deeper queries.
• fickr.search(<callback>,<options>) calls flickr.photos.search using the options defined in the Flickr API reference. User ID is set automatically.
• fickr.listTags(<callback>) is a convenience function calling flickr.tags.getListUser It's useful in generating typeaheads for search or upload tagging utilities.
• fickr.upload(<callback>,<fileBuffer or fileInputFormElement>,<options>) is the most complicated function. In the browser, the three previous functions are accomplished via JSONP due to the CORS limitation. This one is accomplished using an iframe transport method to get around the same limitation. It essentially builds a file upload form in an invisible iframe and submits it to http://up.flickr.com/services/upload/ In order to do that, it manipulates a pre-filled file input DOM element, so that is what it accepts as the second parameter in the browser. Also, since the iframe POST method doesn't have access to the HTTP response, we use a polling method to determine whether or not the upload worked, and return an object containing the most recent fickr.fetch result when it's different from the one before upload (ie. there is a new photo since the upload began). This is a gross hack, and far from bulletproof, but way better than nothing. On the server, everything's easier: just pass a Buffer containing the file's contents and your callback will see the normal HTTP response.