The server Node SDK for Pusher Feeds
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
scripts
src
.babelrc
.flowconfig
.gitignore
.npmignore
package-lock.json
package.json
readme.md
yarn.lock

readme.md

Feeds Server Node reference

This is a server side Node.js library for Feeds service. See the full documentation here

Please note that the reference is annotated with a statically typed dialect like Flow

Importing

Add as a dependency using Yarn or npm.

yarn add pusher-feeds-server

Then import the Feeds constructor.

ES6

// The default export is a Feeds class.
import Feeds from 'pusher-feeds-server';

ES5 (CommonJS)

// The default export is a Feeds class.
var Feeds = require('pusher-feeds-server');

Instantiate the Feeds object

Constructor Feeds takes a single options object with the following properties:

  • instanceLocator:string [required] your instance locator; get this from your dashboard

  • key:string [required] your key; get this from your dashboard

Example

const feeds = new Feeds({
  instanceLocator: your_instance_locator,
  key: your_key,
});

Publish single item to a feed

Publish an item to a feed, and broadcast the item to all subscribers.

Definition

feeds.publish(feedId: string, item: any): Promise<any>

Arguments

  • feedId: The feed ID to publish to. If you publish to a feed that does not exist, it is lazily created.
  • item: Arbitrary JSON representing the item data.

Returns

Promise with Node.js http.request IncomingMessage.

Example

feeds
  .publish(feed_id, {message: 'Hello World!'})
  .then(() => console.log('Succesfully published!'))
  .catch((err) => console.log(err));

Publish multiple items to a feed

Definition

feeds.publishBatch(feedId: string, items: Array<any>): Promise<any>

Arguments

  • feedId: The feed ID to publish to. If you publish to a feed that does not exist, it is lazily created.
  • items: An array of the data of each item. Items are published into the feed in order from the start of the array.

Returns

Promise with Node.js http.request IncomingMessage.

Example

feeds
  .publishBatch(feed_id, [{message: 'Hello A!'}, {message: 'Hello B!'}])
  .then(() => console.log('Succesfully published!'))
  .catch((err) => console.log(err));

Pagination

Query a feed for pages of previously published items. Items are returned in descending order of item ID.

Definition

feeds.paginate(feedId: string, options: ?PaginateOptions)

Arguments

  • feedId: The feed ID to fetch items from.
  • options: An object with the following keys
    • cursor: ?number: the ID of the first item in the page – if not provided, retrieves the most recently published items
    • limit: ?number: the number of items to retrieve, defaults to 50

Returns

Promise of type Promise<PaginateResponse> where PaginateResponse is

items: [Item];
next_cursor: ?string;

and Item is

id: string;
created: number;
data: any;

Example

Get a page containing the last 25 items of the feed "my-feed".

feeds.paginate("my-feed", { limit: 25 }).then(({ items }) => {
  // Do something with each of the items
  items.forEach(...);
});

Delete all items in a feed

Definition

feeds.delete(feedId: string): Promise<any>

Arguments

  • feedId: The feed ID to delete items in.

Returns

Promise with Node.js http.request IncomingMessage.

Example

feeds.delete('newsfeed')
  .then(() => console.log('Succesfully deleted!'))
  .catch((err) => console.log(err));

Authorize clients to access private feeds

This method allows you to authorize your clients for access to a certain feed. Please see auth process diagram and example how to implement this method with collaboration with one of our client side libraries.

Definition

feeds.authorizeFeed(
  payload: AuthorizePayload,
  hasPermissionCallback: (action: ActionType, feedId: string) => Promise<bool> | bool
): Promise<Object>

Arguments

  • payload param is essentially POST request payload (or body) object of type AuthorizePayload (You can use body-parser to parse the POST request body for you). The object must have the following format: (Please note that if you using one of our client libraries they will handle this format for you)
type AuthorizePayload = {
  path: string;
  action: string;
  grant_type: string;
};
  • hasPermissionCallback parameter allows you to grant or deny permission to access a feed based on any information you have in scope (e.g. session data). It should either return a bool, or a promise of one. See the auth-docs for more details.

Returns

A Promise with an authResponse object with the properties listed below which can then be used for client authorization.

{
  access_token: token,
  token_type: token_type,
  expires_in: token_expiry,
  refresh_token: refresh_token
}

Example

Using Express.js and body-parser:

// .... Init express js server
// Register auth endpoint
app.post('/feeds/tokens', (req, res) => {
  // Define hasPermission to be used in authorizeFeed function
  const hasPermission = (action, feedId) => (
    db.find(req.session.userId)
      .then(userId => userId === 'abcd')
  );

  // Authorize user with request payload and hasPermission callback.
  feeds.authorizeFeed(req, hasPermission)
    .then(data => res.send(data))
    .catch(err => {
      res.status(400).send(`${err.name}: ${err.message}`)
    });
});

considering that we have the Express.js http server running on http://localhost:5000 then we can test the auth endpoint with curl:

curl -X POST \
-d "action"="READ" \
-d "path"="feeds/private-my-feed-name/items" \
-d "grant_type"="client_credentials" \
http://localhost:5000/feeds/tokens

Error handling

Since all the public methods on Feeds class returns Promise you should always call .catch() on it to handle Error properly. pusher-feeds-server library is using some custom Errors which extends standart JS Error object. You can import them to your project if would like to use them.

Importing

ES6

import Feeds, {
    UnsupportedGrantTypeError,
    InvalidGrantTypeError,
    ClientError
  } from 'pusher-feeds-server';

ES5 (CommonJS)

var Feeds = require('pusher-feeds-server');
var UnsupportedGrantTypeError = Feeds.UnsupportedGrantTypeError;
var InvalidGrantTypeError = Feeds.InvalidGrantTypeError;
var ClientError = Feeds.ClientError;