Class Reader

General

constructor getUnreadCounts setAllRead

Authentication

Clients authenticate using API tokens. The auth token is used for basic requests (typically HTTP GET) while the post token is shorter-lived (to protect against CSRF) and used for mutations (typically HTTP POST).

getAuthToken setAuthToken getPostToken setPostToken getUserInfo

Feeds

Feeds represent RSS/Atom URLs. See Terminology.

getFeeds addFeed removeFeed renameFeed addFeedTag removeFeedTag

Items

Items represent individual articles/posts. See Terminology.

getItems getItemsById getItemIds addItemTag removeItemTag

Tags

Tags can refer to either user-created tags or states. See Terminology.

getTags renameTag

Utility

ensureStream

General

constructor

  • new Reader(
        config: { url: string; client?: string; autoPostToken?: boolean },
    ): Reader

  • Instantiates a new Reader.

    Parameters

    • config: { url: string; client?: string; autoPostToken?: boolean }
      • url: string

        The base API URL. The main (/reader/api/0/) and auth (/accounts/ClientLogin) endpoint paths will be appended.

      • Optionalclient?: string

        The name to identify as when making requests. Default: libseymour.

      • OptionalautoPostToken?: boolean

        Whether to automatically call Reader#getPostToken and attempt to retry API requests that result in a 400 or 401 response. Default: true

    Returns Reader

    Example

    import Reader from 'libseymour'

    const api = new Reader({ url: 'https://www.example.com/api/greader' })

getUnreadCounts

  • getUnreadCounts(): Promise<IUnreadCount[]>

  • Retrieves a list of streams having unread items. (GET /unread-count)

    Returns Promise<IUnreadCount[]>

setAllRead

  • setAllRead(streamId: string, usMax: number): Promise<OKString>

  • Marks all items in the specified stream as read. (POST /mark-all-as-read)

    Parameters

    • streamId: string

      The target Stream ID. This can generally be a feed, user-created tag, or state. (param=s)

    • usMax: number

      Timestamp (microseconds). Only items with a timestamp less than (older) or equal to this value will be marked as read. (param=ts)

    Returns Promise<OKString>

Authentication

getAuthToken

  • getAuthToken(username: string, password: string): Promise<string>

  • Retreives an auth token for the specified username/password combination. This token will be used for future requests without needing to call setAuthToken.

    Parameters

    • username: string
    • password: string

    Returns Promise<string>

setAuthToken

  • setAuthToken(token: string): void

  • Sets the auth token to be used for future requests.

    Parameters

    • token: string

    Returns void

getPostToken

  • getPostToken(): Promise<string>

  • Retreives a short-lived (for CSRF protection) post token to be used for mutation requests. (GET /token)

    This token will be used for future requests without needing to call setPostToken. This method will automatically be called once before retrying a mutation request where the API has responded with a 400 or 401 status code, unless IConfig#autoPostToken is false.

    Returns Promise<string>

setPostToken

  • setPostToken(token: string): void

  • Sets the short-lived post token to be used for mutation requests.

    Parameters

    • token: string

    Returns void

getUserInfo

  • getUserInfo(): Promise<IUserInfo>

  • Retrieves basic information about the currently-authenticated user. (GET /user-info)

    Returns Promise<IUserInfo>

Feeds

getFeeds

  • getFeeds(): Promise<IFeed[]>

  • Retrieves a list of available feeds and streams. (GET /subscription/list)

    Returns Promise<IFeed[]>

addFeed

  • addFeed(feed: string | INewFeed): Promise<OKString>

  • Adds a feed. (POST /subscription/edit)

    Note: While the original API supported multiple feeds and tags in a single request, support by contemporary aggregators varies. For simplicity, this method handles one feed with an optional user-created tag (often a "category" or "folder") at a time.

    Parameters

    • feed: string | INewFeed

      The feed's URL, or an object with url, title (optional) and tag (optional).

    Returns Promise<OKString>

removeFeed

  • removeFeed(feed: string | string[]): Promise<OKString>

  • Removes one or more feeds. (POST /subscription/edit)

    Parameters

    • feed: string | string[]

      A feed ID or URL, or an array of feed IDs or URLs. Stream ID form optional. (param=s)

    Returns Promise<OKString>

renameFeed

addFeedTag

  • addFeedTag(feed: string | string[], tag: string): Promise<OKString>

  • Adds a user-created tag (often a "category" or "folder") to one or more feeds. (POST /subscription/edit)

    Parameters

    • feed: string | string[]

      A feed ID or URL, or an array of feed IDs or URLs. Stream ID form optional. (param=s)

    • tag: string

      The tag name/id to remove. Stream ID form optional. (param=a)

    Returns Promise<OKString>

removeFeedTag

  • removeFeedTag(feed: string | string[], tag: string): Promise<OKString>

  • Removes a user-created tag (often a "category" or "folder") from one or more feeds. (POST /subscription/edit)

    Parameters

    • feed: string | string[]

      A feed ID or URL, or an array of feed IDs or URLs. Stream ID form optional. (param=s)

    • tag: string

      The tag name/id to remove. Stream ID form optional. (param=r)

    Returns Promise<OKString>

Items

getItems

  • getItems(streamId: string, opts?: IGetFeedItemOpts): Promise<IFeedItem[]>

  • Retrieves a list of items for a given stream. (GET /stream/contents/<streamId>)

    Parameters

    • streamId: string

      A Stream ID. If the provided value is not in Stream ID form it's assumed to refer to a feed ID or URL.

    • opts: IGetFeedItemOpts = {}

      Additional options for the request.

      • Optionalcontinuation?: string

        Continuation key from a previous request, used to fetch the next batch. (param=c)

      • Optionalexclude?: string

        Exclude a streamId. (param=xt)

      • OptionalsMax?: number

        Exclude items newer than this timestamp (seconds). (param=nt)

      • OptionalsMin?: number

        Exclude items older than this timestamp (seconds). (param=ot)

      • Optionalnum?: number

        Number of items per request. Default: 50 (param=n)

      • Optionalsort?: "asc" | "desc"

        Date sort order. Default: desc (param=r)

    Returns Promise<IFeedItem[]>

getItemsById

  • getItemsById(itemId: string | string[]): Promise<IFeedItem[]>

  • Retrieves a list of items having the specified item IDs. (POST /stream/items/contents)

    Note: POST is used to avoid URI length limits when requesting many items. A post token should not be required since no mutations are performed.

    Parameters

    • itemId: string | string[]

      The item ID, or an array of item IDs. (param=i)

    Returns Promise<IFeedItem[]>

getItemIds

  • getItemIds(streamId: string, opts?: IGetFeedItemOpts): Promise<string[]>

  • Retrieves a list of item IDs for a given stream. (GET /stream/items/ids)

    Parameters

    • streamId: string

      A Stream ID. If the provided value is not in Stream ID form (e.g. a URL instead) it's assumed to refer to a feed. (param=s)

    • opts: IGetFeedItemOpts = {}

      Additional options for the request.

      • Optionalcontinuation?: string

        Continuation key from a previous request, used to fetch the next batch. (param=c)

      • Optionalexclude?: string

        Exclude a streamId. (param=xt)

      • OptionalsMax?: number

        Exclude items newer than this timestamp (seconds). (param=nt)

      • OptionalsMin?: number

        Exclude items older than this timestamp (seconds). (param=ot)

      • Optionalnum?: number

        Number of items per request. Default: 50 (param=n)

      • Optionalsort?: "asc" | "desc"

        Date sort order. Default: desc (param=r)

    Returns Promise<string[]>

addItemTag

  • addItemTag(itemId: string | string[], tag: string | string[]): Promise<OKString>

  • Adds one or more tags (user-created or state) to the specified item(s). (POST /edit-tag)

    Parameters

    • itemId: string | string[]

      The item's ID, or an array of item IDs. (param=i)

    • tag: string | string[]

      The tag, or an array of tags, to remove. Stream ID form is required, since both

      • user-created and state tags can be referenced. (param=a)

    Returns Promise<OKString>

removeItemTag

  • removeItemTag(
        itemId: string | string[],
        tag: string | string[],
    ): Promise<OKString>

  • Removes one or more tag (user-created or state) from the specified item(s). (POST /edit-tag)

    Parameters

    • itemId: string | string[]

      The item's ID, or an array of item IDs. (param=i)

    • tag: string | string[]

      The tag, or an array of tags, to remove. Stream ID form is required, since both user-created and state tags can be referenced. (param=r)

    Returns Promise<OKString>

Tags

getTags

  • getTags(): Promise<ITag[]>

  • Retrieves a list of available tags. (GET /tag/list)

    Returns Promise<ITag[]>

renameTag

  • renameTag(tag: string, newTag: string): Promise<OKString>

  • Renames a user-created tag (often a "category" or "folder" for a feed, or "label" for an item). (POST /rename-tag)

    Parameters

    • tag: string

      Current tag name/id. Stream ID form optional. (param=s)

    • newTag: string

      New tag name/id. Stream ID form optional. (param=dest)

    Returns Promise<OKString>

Utility

StaticensureStream

  • ensureStream(input: string, type: "FEED" | "LABEL" | "STATE"): string

  • A utility method to ensure a string is in Stream ID form. If it is, the string is returned verbatim. If not, the specified stream type's prefix is prepended.

    Parameters

    • input: string

      The input string.

    • type: "FEED" | "LABEL" | "STATE"

      The desired Stream ID form, only if the input is not already in Stream ID form.

    Returns string

Settings

On This Page

General
Authentication
Feeds
Items
Tags
Utility