JS / Browser Client - Build Activity Feeds & Streams with GetStream.io
Switch branches/tags
Clone or download
Latest commit d376cef Oct 17, 2018
Permalink
Failed to load latest commit information.
bin npm run lint in travis Sep 17, 2018
dist 3.22.0 Oct 17, 2018
docs/getstream Fix a typo Oct 27, 2017
dotgit Use npm in hook Sep 17, 2018
src Fix import Oct 15, 2018
test Merge pull request #202 from GetStream/better-not-found-errors Oct 16, 2018
types/getstream prettify + fix lints Sep 17, 2018
.babelrc Use unambigous sourceType in babel Sep 10, 2018
.editorconfig Add editorconfig Sep 17, 2018
.eslintignore Ignore some directories for prettifying + linting Sep 17, 2018
.eslintrc.json Fix eslint config Aug 17, 2018
.gitignore Ignore .nyc_output Jul 31, 2018
.ignore [SF-12] Enrich: Change tests to handle enriching of user IDs and acti… Jul 9, 2018
.jscsrc Initial import Oct 6, 2016
.jsdoc update jsdoc and ignore osx silly files Oct 28, 2015
.npmignore Don't publish docs and tests to make the package much smaller Aug 31, 2018
.prettierignore Ignore some directories for prettifying + linting Sep 17, 2018
.prettierrc Use trailingComma: "all" for prettier Sep 17, 2018
.travis.yml Run cloud tests Aug 31, 2018
CHANGELOG Update CHANGELOG Oct 17, 2018
LICENSE Fix incorrect license copyright reference. Mar 16, 2017
README.md add activity partial update example Jul 31, 2018
bower.json Added type definitons, tests and linter Sep 1, 2017
karma.ci.config.js prettify + fix lints Sep 17, 2018
karma.config.js Fix lints Sep 17, 2018
package-lock.json 3.22.0 Oct 17, 2018
package.json 3.22.0 Oct 17, 2018
webpack.config.js Fix lints Sep 17, 2018

README.md

Stream-JS

Build Status Sauce Test Status

NPM

stream-js is the official JavaScript client for Stream, a web service for building scalable newsfeeds and activity streams.

Note that there is also a higher level Node integration which hooks into your ORM.

You can sign up for a Stream account at https://getstream.io/get_started.

Installation

Install from NPM

npm install getstream

Using JS deliver

<script src="https://cdn.jsdelivr.net/npm/getstream/dist/js_min/getstream.js"></script>

Install by downloading the JS file

JS / Minified JS

Full documentation

Documentation for this JavaScript client are available at the Stream website.

Using with React Native

This package can be integrated into React Native applications. Remember to not expose the App Secret in browsers, "native" mobile apps, or other non-trusted environments.

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 (see below for stream-js or https://getstream.io/docs/ for other languages)
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 useful 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);

// Updating parts of an activity
var set = {
  'product.price': 19.99,
  'shares': {
    'facebook': '...',
    'twitter': '...'
  },
}
var unset = [
  'daily_likes',
  'popularity'
]
// ...by ID
client.activityPartialUpdate({
  id: '54a60c1e-4ee3-494b-a1e3-50c06acb5ed4',
  set: set,
  unset: unset,
})
// ...or by combination of foreign ID and time
client.activityPartialUpdate({
  foreignID: 'product:123',
  time: '2016-11-10T13:20:00.000000',
  set: set,
  unset: unset,
})

// 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);

// update the 'to' fields on an existing activity
// client.feed("user", "ken").function (foreign_id, timestamp, new_targets, added_targets, removed_targets)
// new_targets, added_targets, and removed_targets are all arrays of feed IDs
// either provide only the `new_targets` parameter (will replace all targets on the activity),
// OR provide the added_targets and removed_targets parameters
// NOTE - the updateActivityToTargets method is not intended to be used in a browser environment.
client.feed("user", "ken").updateActivityToTargets("foreign_id:1234", timestamp, ["feed:1234"])
client.feed("user", "ken").updateActivityToTargets("foreign_id:1234", timestamp, null, ["feed:1234"])
client.feed("user", "ken").updateActivityToTargets("foreign_id:1234", timestamp, null, null, ["feed:1234"])

Realtime (Faye)

Stream uses Faye for realtime notifications. Below is quick guide to subscribing 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', 'APP_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, 'APP_ID');
user1 = client.feed('user', '1', 'feedtoken');
// subscribe to the changes
var subscription = user1.subscribe(function (data) {
	console.log(data);
});
// 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.

Node version requirements & Browser support

This API Client project requires Node.js v6 at a minimum.

The project is supported in line with the Node.js Foundation Release Working Group.

See the Travis configuration and Sauce Test Status for details of how it is built, tested and packaged.

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

Copyright and License Information

Copyright (c) 2015-2018 Stream.io Inc, and individual contributors. All rights reserved.

See the file "LICENSE" for information on the history of this software, terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.