@enricu/flickr-sdk v4.0.0

@enricu/flickr-sdk

Almost certainly the best Flickr API client in the world for node and the browser

Install

$ npm install @enricu/flickr-sdk

Usage

@enricu/flickr-sdk is based on superagent and all methods that make API calls will return a superagent Request instance configured for the request. This means that you can do anything with Flickr requests that you can do with superagent.

The Flickr API is divided into several services:

• The REST API service, which provides access to Flickr data
• The OAuth service, which authenticates users via OAuth 1.0
• The Feeds service, which provides feeds of public Flickr data
• The Upload service, where you can upload photos!
• The Replace service, where you can replace photos you previously uploaded

Example

var Flickr = require('@enricu/flickr-sdk');

Browser Usage

Since OAuth 1.0 requires your application's key and secret to sign requests, @enricu/flickr-sdk does not support this authentication method in the browser. Upload, Replace, and REST API calls that require authentication will not work without a valid OAuth signature. You can still use @enricu/flickr-sdk to call REST API methods that don't require authentication or to get public feeds.

@enricu/flickr-sdk has been tested with browserify but should work with other client-side module bundlers like webpack and rollup. If you need a standalone browser-ready version of @enricu/flickr-sdk, each release on npm will contain a browserified version of this module at node_modules/flickr-sdk/flickr-sdk.js. It is not minified.

Flickr

All of the REST API methods are available on the Flickr prototype. Each method accepts a single parameter which is an optional hash of arguments. Refer to the REST API docs for the full list of methods and their supported arguments.

Kind: global class

• Flickr
  • new Flickr(auth)
  • .OAuth
    • new OAuth(consumerKey, consumerSecret)
    • instance
      • .request(oauthCallback) ⇒ Request
      • .authorizeUrl(requestToken, [perms]) ⇒ String
      • .verify(oauthToken, oauthVerifier, tokenSecret) ⇒ Request
      • .plugin(oauthToken, oauthTokenSecret) ⇒ function
    • static
      • .createPlugin(consumerKey, consumerSecret, oauthToken, oauthTokenSecret) ⇒ function
  • .Upload ⇐ Request
    • new Upload(auth, file, [args])
  • .Replace ⇐ Request
    • new Replace(auth, photoID, file, [args])
  • .Feeds
    • new Feeds([args])
    • .publicPhotos([args]) ⇒ Request
    • .friendsPhotos(args) ⇒ Request
    • .favePhotos(args) ⇒ Request
    • .groupDiscussions(args) ⇒ Request
    • .groupPool(args) ⇒ Request
    • .forum([args]) ⇒ Request
    • .recentActivity(args) ⇒ Request
    • .recentComments(args) ⇒ Request

new Flickr(auth)

Creates a new Flickr REST API client.

You must pass a superagent plugin or your API key as the first parameter. For methods that don't require authentication, you can simply provide your API key. For methods that do require authentication, use the OAuth plugin.

Example (Get info about a public photo with your API key)

var flickr = new Flickr(process.env.FLICKR_API_KEY);

flickr.photos.getInfo({
  photo_id: 25825763 // sorry, @dokas
}).then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Example (Searching for public photos with your API key)

var flickr = new Flickr(process.env.FLICKR_API_KEY);

flickr.photos.search({
  text: 'doggo'
}).then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Example (Authenticate as a user with the OAuth plugin)

var flickr = new Flickr(Flickr.OAuth.createPlugin(
  process.env.FLICKR_CONSUMER_KEY,
  process.env.FLICKR_CONSUMER_SECRET,
  process.env.FLICKR_OAUTH_TOKEN,
  process.env.FLICKR_OAUTH_TOKEN_SECRET
));

flickr.test.login().then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Flickr.OAuth

Kind: static class of Flickr

• .OAuth
  • new OAuth(consumerKey, consumerSecret)
  • instance
    • .request(oauthCallback) ⇒ Request
    • .authorizeUrl(requestToken, [perms]) ⇒ String
    • .verify(oauthToken, oauthVerifier, tokenSecret) ⇒ Request
    • .plugin(oauthToken, oauthTokenSecret) ⇒ function
  • static
    • .createPlugin(consumerKey, consumerSecret, oauthToken, oauthTokenSecret) ⇒ function

new OAuth(consumerKey, consumerSecret)

Creates a new OAuth service instance. You can use this service to request and validate OAuth tokens, as well as generate an auth plugin suitable for use with the REST and Upload services.

You need to register an application to obtain your consumerKey and consumerSecret.

OAuth 1.0 requires your consumer secret to sign calls, and you should never expose secrets to the browser.

Example

var oauth = new Flickr.OAuth(
  process.env.FLICKR_CONSUMER_KEY,
  process.env.FLICKR_CONSUMER_SECRET
);

oAuth.request(oauthCallback) ⇒ Request

Get a Request Token using the consumer key.

Kind: instance method of OAuth
See

• https://github.com/visionmedia/superagent
• https://www.flickr.com/services/api/auth.oauth.html#request_token

Example

oauth.request('http://localhost:3000/oauth/callback').then(function (res) {
  console.log('yay!', res);
}).catch(function (err) {
  console.error('bonk', err);
});

oAuth.authorizeUrl(requestToken, perms) ⇒ String

Returns the authorization url for requestToken. You may also pass the perms your app is requesting as read (the default), write, or delete. Your application should redirect the user here to ask them to verify your request token.

Kind: instance method of OAuth
See: https://www.flickr.com/services/api/auth.oauth.html#authorization

Example

var url = oauth.authorizeUrl(requestToken); // "https://www.flickr.com/services/oauth..."

res.setHeader("Location", url);
res.statusCode = 302;
res.end();

oAuth.verify(oauthToken, oauthVerifier, tokenSecret) ⇒ Request

Verify an OAuth token using the verifier and token secret. If your user has indeed verified your request token, you will receive an OAuth token and secret back, as well as some very basic profile information. You can now use this token and secret to make calls to the REST API.

Kind: instance method of OAuth
See

• https://github.com/visionmedia/superagent
• https://www.flickr.com/services/api/auth.oauth.html#access_token

Example

oauth.verify(oauthToken, oauthVerifier, tokenSecret).then(function (res) {
  console.log('oauth token:', res.body.oauth_token);
  console.log('oauth token secret:', res.body.oauth_token_secret);
}).catch(function (err) {
 console.log('bonk', err);
});

oAuth.plugin(oauthToken, oauthTokenSecret) ⇒ function

Returns an oauth plugin for this consumer key and secret.

Kind: instance method of OAuth

Example

var flickr = new Flickr(oauth.plugin(
  oauthToken,
  oauthTokenSecret
));

OAuth.createPlugin(consumerKey, consumerSecret, oauthToken, oauthTokenSecret) ⇒ function

Returns an oauth plugin for this consumer key, consumer secret, oauth token and oauth token secret,

Kind: static method of OAuth

Example

var flickr = new Flickr(Flickr.OAuth.createPlugin(
  process.env.FLICKR_CONSUMER_KEY,
  process.env.FLICKR_CONSUMER_SECRET,
  process.env.FLICKR_OAUTH_TOKEN,
  process.env.FLICKR_OAUTH_TOKEN_SECRET
));

Flickr.Upload ⇐ Request

Kind: static class of Flickr
Extends: Request
See: https://www.flickr.com/services/api/upload.api.html

new Upload(auth, file, args)

Creates a new Upload service instance. Since the Upload API only does one thing (upload files), an Upload instance is simply a Request subclass.

The Upload endpoint requires authentication. You should pass a configured instance of the OAuth plugin to upload photos on behalf of another user.

Example

var upload = new Flickr.Upload(auth, 'upload.png', {
  title: 'Works on MY machine!'
});

upload.then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Flickr.Replace ⇐ Request

Kind: static class of Flickr
Extends: Request
See: https://www.flickr.com/services/api/replace.api.html

new Replace(auth, photoID, file, args)

Creates a new Replace service instance. Since the Replace API only does one thing (replace files), an Replace instance is simply a Request subclass.

The Replace endpoint requires authentication. You should pass a configured instance of the OAuth plugin to replace photos on behalf of another user.

Example

var replace = new Flickr.Replace(auth, 41234567890, 'replace.png', {
  title: 'Now in pink!'
});

replace.then(function (res) {
  console.log('yay!', res.body);
}).catch(function (err) {
  console.error('bonk', err);
});

Flickr.Feeds

Kind: static class of Flickr

• .Feeds
  • new Feeds([args])
  • .publicPhotos([args]) ⇒ Request
  • .friendsPhotos(args) ⇒ Request
  • .favePhotos(args) ⇒ Request
  • .groupDiscussions(args) ⇒ Request
  • .groupPool(args) ⇒ Request
  • .forum([args]) ⇒ Request
  • .recentActivity(args) ⇒ Request
  • .recentComments(args) ⇒ Request

new Feeds(args)

Creates a new Feeds service instance. You can use this instance to explore and retrieve public Flickr API data.

Example

var feeds = new Flickr.Feeds();

feeds.publicPhotos(args) ⇒ Request

Returns a list of public content matching some criteria.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_public/

feeds.friendsPhotos(args) ⇒ Request

Returns a list of public content from the contacts, friends & family of a given person.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_friends/

feeds.favePhotos(args) ⇒ Request

Returns a list of public favorites for a given user.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_faves/

feeds.groupDiscussions(args) ⇒ Request

Returns a list of recent discussions in a given group.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/groups_discuss/

feeds.groupPool(args) ⇒ Request

Returns a list of things recently added to the pool of a given group.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/groups_pool/

feeds.forum(args) ⇒ Request

Returns a list of recent topics from the forum.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/forums/

feeds.recentActivity(args) ⇒ Request

Returns a list of recent comments on photostream and sets belonging to a given user.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/activity/

feeds.recentComments(args) ⇒ Request

Returns a list of recent comments that have been commented on by a given person.

Kind: instance method of Feeds
See: https://www.flickr.com/services/feeds/docs/photos_comments/

License

Code licensed under the MIT license. See LICENSE file for terms.