Class: Feedly

Defined in:

src/feedly.coffee

Overview

Talk to the Feedly API.

All methods will ensure a valid authentication dance has occurred, and perform the dance if necessary.

All of the methods that take a callback also return a Q promise - the callback is therefore optional.

WARNING: by default, this class stores state information such as your access token in ~/.feedly by default.

Instance Method Summary

# (promise(String)) refresh(cb) Refresh the auth token manually.
# (promise()) logout(cb) Discard all tokens
# (promise(Array(Category))) categories(cb) Fetch the list of categories
# (promise()) setCategoryLabel(id, label, cb) Set the label for a category.
# (promise()) deleteCategory(id, cb) Delete a category.
# (promise(Entry) or promise(Array(Entry))) entry(id, cb) Get one or more entries
# (promise()) createEntry(entry, cb) Create an entry.
# (promise(Feed)) feed(id, cb) Get meta-data about a feed or list of feeds
# (promise(Counts)) counts(autorefresh, newerThan, streamId, cb) Get unread counts.
# (void) markEntryRead(ids, cb) Mark articles as read.
# (void) markEntryUnread(ids, cb) Mark articles as unread.
# (void) markFeedRead(ids, since, cb) Mark feed(s) as read.
# (void) markCategoryRead(ids, since, cb) Mark category(s) as read.
# (promise(Reads)) reads(newerThan, cb) Get the latest read operations (to sync local cache).
# (promise(Tags)) tags(newerThan, cb) Get the latest tagged entry ids
# (promise(Prefs)) preferences(cb) Get the current user's preferences
# (promise(Prefs)) updatePreferences(prefs, cb) Update the preferences of the user
# (promise(Profile)) profile(cb) Get the current user's profile
# (promise(Profile)) updateProfile(profile, cb) Update the profile of the user
# (promise(Array(Feeds))) searchFeeds(query, results = 20, cb) Find feeds based on title, url or #topic
# (promise(Shortened)) shorten(entry, cb) Create a shortened URL for an entry.
# (promise(Array(Page))) stream(id, options, cb) Get a list of entry ids for a specific stream.
# (promise(Array(Page))) contents(id, continuation, cb) Get the content of a stream
# (promise(Array(Subscription))) subscriptions(cb) Get the user’s subscriptions
# (promise()) subscribe(url, categories, cb) Subscribe to a feed
# (promise()) unsubscribe(id, cb) Unsubscribe from a feed
# (promise()) tagEntry(entry, tags, cb) Tag an existing entry or entries
# (promise()) setTagLabel(tag, label, cb) Change a tag label
# (promise()) untagEntries(entries, tags, cb) Untag entries
# (promise()) deleteTags(tags, cb) Delete tags

Constructor Details

# (void) constructor(options)

Parameters:

options ( Object ) — options for the API

Options Hash: (options):

port ( int ) — TCP port to listen on for callbacks. (default: 0, which means to pick a random port)
base ( String ) — The root URL of the API. (default: 'http://cloud.feedly.com')
config_file ( String ) — File in which state information such as the access token and refresh tokens are stored. Tildes are expanded as needed. (default: '~/.feedly')
html_file ( String ) — File that contains the HTML to give to the web browser after it is redirected to the one-shot web server that we'll be running. (default: '../html/index.html')
html_text ( String ) — If html_file is null or the file can't be read, use this text instead. (default: 'No HTML found')
slop ( int ) — If there is less than this amount of time (in milliseconds) between now and the expiration of the access token, refresh the token. (default: 3600000)
client_id ( String ) — The API client ID. (REQUIRED)
client_secret ( String ) — The API client Secret. (REQUIRED)

Instance Method Details

# (promise(String)) refresh(cb)

Refresh the auth token manually. If the current refresh token is not valid, authenticate again.

Parameters:

cb ( function(error, authToken) ) — Optional callback

Returns:

( promise(String) ) — new auth token

# (promise()) logout(cb)

Discard all tokens

Parameters:

cb ( function(error) ) — Optional callback

Returns:

( promise() ) — logout finished

# (promise(Array(Category))) categories(cb)

Fetch the list of categories

Parameters:

cb ( function(error, Array(Category)) ) — Optional callback

Returns:

( promise(Array(Category)) ) — list of categories

# (promise()) setCategoryLabel(id, label, cb)

Set the label for a category.

Parameters:

id ( String ) — the category to modify
label ( String ) — the new label
cb ( function(error) ) — Optional callback

Returns:

( promise() ) — complete

# (promise()) deleteCategory(id, cb)

Delete a category.

Parameters:

id ( String ) — the category to delete
cb ( function(error) ) — Optional callback

Returns:

( promise() ) — complete

# (promise(Entry) or promise(Array(Entry))) entry(id, cb)

Get one or more entries

Parameters:

id ( String or Array(String) ) — the entry or entries to retrieve
cb ( function(error, promise(Entry) or promise(Array(Entry))) ) — Optional callback

Returns:

( promise(Entry) or promise(Array(Entry)) ) — the entry(s)

# (promise()) createEntry(entry, cb)

Create an entry. Thiss call is useful to inject entries not coming from a feed, into a user’s account. The entries created will only be available through the tag streams of the respective tags passed.

Parameters:

entry ( Entry ) — See the [Feedly API docs] (http://developer.feedly.com/v3/entries/#create-and-tag-an-entry) for more information.
cb ( function(error) ) — Optional callback

Returns:

( promise() ) — complete

# (promise(Feed)) feed(id, cb)

Get meta-data about a feed or list of feeds

Parameters:

id ( String or Array(String) ) — the ID or list of IDs of the feed(s)
cb ( function(error, Feed) ) — Optional callback

Returns:

promise(Feed)

# (promise(Counts)) counts(autorefresh, newerThan, streamId, cb)

Get unread counts. In theory, newerThan and streamId can be used to reduce the counts that are returned, but I didn't see evidence of that in practice.

Parameters:

autorefresh ( Boolean ) — lets the server know if this is a background auto-refresh or not. In case of very high load on the service, the server can deny access to background requests and give priority to user facing operations. (optional)
newerThan ( Date ) — timestamp used as a lower time limit, instead of the default 30 days (optional)
streamId ( String ) — A user or system category can be passed to restrict the unread count response to feeds in this category. (optional)
cb ( function(error, Counts) ) — optional callback

Returns:

promise(Counts)

# (void) markEntryRead(ids, cb)

Mark articles as read.

Parameters:

ids ( Array(String) ) — article IDs to mark read
cb ( function(error) ) — optional callback

# (void) markEntryUnread(ids, cb)

Mark articles as unread.

Parameters:

ids ( Array(String) ) — article IDs to mark unread
cb ( function(error) ) — optional callback

# (void) markFeedRead(ids, since, cb)

Mark feed(s) as read.

Parameters:

id ( Array(String) ) — feed ID to mark read
since ( String or Date ) — optional last entry ID read or timestamp last read
cb ( function(error) ) — optional callback

# (void) markCategoryRead(ids, since, cb)

Mark category(s) as read.

Parameters:

id ( Array(String) ) — feed ID to mark read
since ( String or Date ) — optional last entry ID read or timestamp last read
cb ( function(error) ) — optional callback

# (promise(Reads)) reads(newerThan, cb)

Get the latest read operations (to sync local cache).

Parameters:

newerThan ( Date ) — Optional start date
cb ( function(error, Reads) ) — Optional callback

Returns:

promise(Reads)

# (promise(Tags)) tags(newerThan, cb)

Get the latest tagged entry ids

Parameters:

newerThan ( Date ) — Optional start date
cb ( function(error, Tags) ) — Optional callback

Returns:

promise(Tags)

# (promise(Prefs)) preferences(cb)

Get the current user's preferences

Parameters:

cb ( function(error, Prefs) ) — Optional callback

Returns:

promise(Prefs)

# (promise(Prefs)) updatePreferences(prefs, cb)

Update the preferences of the user

Parameters:

prefs ( Object ) — the preferences to update, use "==DELETE==” as the value in order to delete a preference.
cb ( function(error, Prefs) ) — Optional callback

Returns:

promise(Prefs)

# (promise(Profile)) profile(cb)

Get the current user's profile

Parameters:

cb ( function(error, Profile) ) — Optional callback

Returns:

promise(Profile)

# (promise(Profile)) updateProfile(profile, cb)

Update the profile of the user

Parameters:

profile ( Object ) — the profile to update
cb ( function(error, Profile) ) — Optional callback

Returns:

promise(Profile)

# (promise(Array(Feeds))) searchFeeds(query, results = 20, cb)

Find feeds based on title, url or #topic

Parameters:

query ( string ) — the string to search for
results ( int ) — the maximum number of results to return (default: 20)
cb ( function(error, Array(Feeds)) ) — Optional callback

Returns:

promise(Array(Feeds))

# (promise(Shortened)) shorten(entry, cb)

Create a shortened URL for an entry. The short URL is unique for a given entry id, user and application.

Parameters:

entry ( string ) — The entry ID to shorten
cb ( function(error, Shortened) ) — Optional callback

Returns:

promise(Shortened)

# (promise(Array(Page))) stream(id, options, cb)

Get a list of entry ids for a specific stream.

   or an object with stream request parameters

Parameters:

id ( string ) — the id of the stream
options ( string|object ) — a continuation id is used to page
cb ( function(error, Array(Page)) ) — Optional callback

Returns:

promise(Array(Page))

# (promise(Array(Page))) contents(id, continuation, cb)

Get the content of a stream

Parameters:

id ( string ) — the id of the stream
continuation ( string ) — a continuation id is used to page
cb ( function(error, Array(Page)) ) — Optional callback

Returns:

promise(Array(Page))

# (promise(Array(Subscription))) subscriptions(cb)

Get the user’s subscriptions

Parameters:

cb ( function(error, Array(Subscription)) ) — Optional callback

Returns:

promise(Array(Subscription))

Subscribe to a feed

Parameters:

url ( string ) — the URL of the feed to subscribe to
categories ( string or Array(string) ) — category(s) for the subscription
cb ( function(error) ) — Optional callback

Returns:

promise()

# (promise()) unsubscribe(id, cb)

Unsubscribe from a feed

Parameters:

id ( string ) — the ID of the feed to unsubscribe from
cb ( function(error) ) — Optional callback

Returns:

promise()

# (promise()) tagEntry(entry, tags, cb)

Tag an existing entry or entries

Parameters:

entry ( string or Array(string) ) — the entry(s) to tag
tags ( string Array(string) ) — tag(s) to apply to the entry
cb ( function(error) ) — Optional callback

Returns:

promise()

# (promise()) setTagLabel(tag, label, cb)

Change a tag label

Parameters:

tag ( string ) — the tag to modify
label ( string ) — new label for the tag
cb ( function(error) ) — Optional callback

Returns:

promise()

# (promise()) untagEntries(entries, tags, cb)

Untag entries

Parameters:

entries ( string or Array(string) ) — the ID(s) of the entries to modify
tags ( string or Array(string) ) — the tag(s) to remove
cb ( function(error) ) — Optional callback

Returns:

promise()

# (promise()) deleteTags(tags, cb)

Delete tags

Parameters:

tags ( string or Array(string) ) — the tag(s) to remove
cb ( function(error) ) — Optional callback

Returns:

promise()