Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

getstream-fix-signing

GetStream8BSD-3-Clause3.5.1

The official low-level GetStream.io client for Node.js and the browser. Branched to fix issue where activity.to is already signed.

readme

Stream-js

Build Status Coverage Status Dependencies up to date

stream-js is the official JavaScript client for Stream, a web service for building scalable newsfeeds and activity streams. The full documentation is available on GetStream.io/docs. Note that there is also a higher level Node integration which hooks into your ORM.

Installation

Install from NPM

npm install getstream

Install using bower

bower install getstream

Install by downloading the JS file

JS / Minified JS

Using with React Native

For use with React Native be sure to use webpack as your bundler. For a bootstrap project for React native and webpack see this project

Usage

var stream = require('getstream');
// Instantiate a new client (server side)
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET');
// Optionally supply the app identifier and an object specifying the data center to use
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', 'APP_ID', { location: 'us-west' });
// Instantiate a new client (client side)
client = stream.connect('YOUR_API_KEY');
// Find your API keys here https://getstream.io/dashboard/

// Instantiate a feed object server side
user1 = client.feed('user', '1');
// Instantiate a feed object client side
// Generate a feed's token using server side signing
user1 = client.feed('user', '1', 'FEED_TOKEN');

// Get activities from 5 to 10 (slow pagination)
user1.get({limit:5, offset:5}, callback);
// (Recommended & faster) Filter on an id less than a given UUID
user1.get({limit:5, id_lt:"e561de8f-00f1-11e4-b400-0cc47a024be0"});

// All API calls are performed asynchronous and return a Promise object
user1.get({limit:5, id_lt:"e561de8f-00f1-11e4-b400-0cc47a024be0"})
    .then(function(body) { /* on success */ })
    .catch(function(reason) { /* on failure, reason.error contains an explanation */ });

// Create a new activity
activity = {'actor': 1, 'verb': 'tweet', 'object': 1, 'foreign_id': 'tweet:1'};
user1.addActivity(activity);
// Create a bit more complex activity
activity = {'actor': 1, 'verb': 'run', 'object': 1, 'foreign_id': 'run:1',
    'course': {'name': 'Golden Gate park', 'distance': 10},
    'participants': ['Thierry', 'Tommaso'],
    'started_at': new Date()
};
user1.addActivity(activity);

// Remove an activity by its id
user1.removeActivity("e561de8f-00f1-11e4-b400-0cc47a024be0");
// or remove by the foreign id
user1.removeActivity({foreignId: 'tweet:1'});

// mark a notification feed as read
notification1 = client.feed('notification', '1');
var params = {mark_read: true};
notification1.get(params);

// mark a notification feed as seen
var params = {mark_seen:true};
notification1.get(params);

// Follow another feed
user1.follow('flat', '42');

// Stop following another feed
user1.unfollow('flat', '42');

// Stop following another feed while keeping previously published activities
// from that feed
user1.unfollow('flat', '42', { keepHistory: true });

// Follow another feed without copying the history
user1.follow('flat', '42', { limit: 0 });

// List followers, following
user1.followers({limit: '10', offset: '10'});
user1.following({limit: '10', offset: '0'});

// all methods support callback as the last argument
user1.follow('flat', '42');

// adding multiple activities
activities = [
    {'actor': 1, 'verb': 'tweet', 'object': 1},
    {'actor': 2, 'verb': 'tweet', 'object': 3},
];
user1.addActivities(activities);

// specifying additional feeds to push the activity to using the to param
// especially usefull for notification style feeds
to = ['user:2', 'user:3'];
activity = {'to': to, 'actor': 1, 'verb': 'tweet', 'object': 1, 'foreign_id': 'tweet:1'};
user1.addActivity(activity);

// adding one activity to multiple feeds
var feeds = ['flat:1', 'flat:2', 'flat:3', 'flat:4'];
activity = {
  'actor': 'User:2',
  'verb': 'pin',
  'object': 'Place:42',
  'target': 'Board:1'
};

client.addToMany(activity, feeds);

// Batch create follow relations (let flat:1 follow user:1, user:2 and user:3 feeds in one single request)
var follows = [
  {'source': 'flat:1', 'target': 'user:1'},
  {'source': 'flat:1', 'target': 'user:2'},
  {'source': 'flat:1', 'target': 'user:3'}
];

client.followMany(follows);

// creating a feed token server side
token = user1.token;
// passed to client via template or api and initialized as such
user1 = client.feed('user', '1', token);

// creating a read-only feed token server side
readonlyToken = client.feed('user', '1').getReadOnlyToken();
// passed to client via template or api and initialized as such
user1 = client.feed('user', '1', readonlyToken);

// Create redirect urls
var impression = {
    'content_list': ['tweet:1', 'tweet:2', 'tweet:3'], 
    'user_data': 'tommaso', 
    'location': 'email',
    'feed_id': 'user:global'
};
var engagement = {
    'content': 'tweet:2', 
    'label': 'click',
    'position': 1, 
    'user_data': 'tommaso', 
    'location': 'email',
    'feed_id': 
    'user:global'
};
var events = [impression, engagement];
var redirectUrl = client.createRedirectUrl('http://google.com', 'user_id', events);

Realtime (Faye)

Stream uses Faye for realtime notifications. Below is quick quide to subcribing to feed changes

var stream = require('getstream');
// NOTE: the site id is needed for subscribing
// server side example:
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', 'SITE_ID');
user1 = client.feed('user', '1');
// same two lines but client side (generate the feed token server side)
client = stream.connect('YOUR_API_KEY', null, 'SITE_ID');
user1 = client.feed('user', '1', 'feedtoken');
// subscribe to the changes
var subscription = user1.subscribe(function callback() {
    /* callback */
});
// now whenever something changes to the feed user 1
// the callback will be called

// To cancel a subscription you can call cancel on the
// object returned from a subscribe call.
// This will remove the listener from this channel.
subscription.cancel();

Docs are available on GetStream.io.

Contributing

First, make sure you can run the test suite. Tests are run via Mocha

mocha test/integration/index.js test/unit/index.js
# browser version (needs to be build through gulp build:test)
test/browser/test.html
# coverage
mocha test/cov.js -R html-cov > cov.html

Releasing

Make sure your working directory is clean. And run:

npm install
npm version [ major | minor | patch ]
npm publish

changelog

================

Change history

3.4.0

:released-date: 2016-06-28 :by: Matthisk Heimensen

  • add getReadOnlyToken and getReadWriteToken method to feed instances
  • Update Faye to 1.2.0

3.3.0

:released-date: 2016-06-27 :by: Tommaso Barbugli

  • Pin down all dependencies

3.2.0

:release-date: 2016-03-30 :by: Tommaso Barbugli

  • Added support for keep_history parameter on unfollow

3.1.2

:release-date: 2016-03-01 :by: Matthisk Heimensen

  • Stream-JS is now compatible with React-Native
  • dependency browser-request fork changed to xmlhttp-request hosted on npm

3.1.1

:release-date: 2016-02-29 :by: Matthisk Heimensen

  • Stream-JS is now compatible with React-Native
  • dependency browser-request updated to 0.3.4

3.1.0

:release-date: 2016-02-22 :by: Matthisk Heimensen

  • Added support for update_activity API
  • Added support for activity_copy_limit to limit the amount of activities copied by client.followMany
  • dependency request updated to 2.67.0
  • dependency qs updated to 6.0.1
  • dependency faye updated to 1.1.2

3.0.0

:release-date: 2015-10-28 :by: Matthisk Heimensen

  • Breaking change: Functions performing an XHR Request no longer return the request object, instead they return a Promise
  • Added support for add_to_many api call (i.e. client.addToMany) to add one activity to many feeds
  • Added support for follow_many api call (i.e. client.followMany) to create multiple follow relations in one request
  • Added support to create a redirect url (i.e. client.createRedirectUrl) to track events via stream's analytics platform
  • Added support for follow_copy_limit API parameter on follow.
  • Added option to enable JWT token expiration (default behavior is no expiration) through option: { expireTokens: true }
  • Removed Buffer as a dependency of lib/signing.js to reduce distributable size for the browser. Instead use Base64 lib for base64 encoding.
  • Generated API documentation in /docs
  • Enforce code style through jscs and jshint during the build (i.e. gulp lint)

2.1.0

:release-date: 2014-12-19 :by: Thierry Schellenbach

  • Added location support to reduce latency
  • Heroku location support

2.0.5

:release-date: 2014-11-25 :by: Thierry Schellenbach

  • Allow "-" in feed id for compatibility with mongo ids

2.0.4

:release-date: 2014-11-18 :by: Thierry Schellenbach

  • Added validation on feed slug and user id

2.0.0

:release-date: 2014-11-10 :by: Thierry Schellenbach

  • Breaking change: New style feed syntax, client.feed('user', '1') instead of client.feed('user:3')
  • Breaking change: New style follow syntax, feed.follow('user', 3)
  • API versioning support
  • Cleanup of API client codebase and naming

1.0.6

:release-date: 2014-09-16 :by: Thierry Schellenbach

  • Bugfix for filtering support

1.0.5

:release-date: 2014-09-15 :by: Thierry Schellenbach

  • Added user agent for getstream.io analytics
  • Added support for filtering followers and following by providing the feeds argument

1.0.4

:release-date: 2014-09-12 :by: Thierry Schellenbach

  • Added support for attaching global handlers via client.on('request', callback)
  • Add support for mark read and mark seen (notifications feeds)