pusher-feeds-server v0.8.2

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;