koolkanya-zulip v2.0.18

zulip-js

Javascript library to access the Zulip API

Usage

Initialization

With API Key

const zulip = require('zulip-js');
const config = {
  username: process.env.ZULIP_USERNAME,
  apiKey: process.env.ZULIP_API_KEY,
  realm: process.env.ZULIP_REALM
};

zulip(config).then(zulip => {
  // The zulip object now initialized with config
  zulip.streams.subscriptions.retrieve().then(res => {
    console.log(res);
  });
});

With Username & Password

You will need to first retrieve the API key by calling zulip(config) and then use the zulip object that it passes to .then()

const zulip = require('zulip-js');
const config = {
  username: process.env.ZULIP_USERNAME,
  password: process.env.ZULIP_PASSWORD,
  realm: process.env.ZULIP_REALM
};

//Fetch API Key
zulip(config).then(zulip => {
  // The zulip object now contains the API Key
  zulip.streams.subscriptions.retrieve().then(res => {
    console.log(res);
  });
});

With zuliprc

Create a file called zuliprc (in the same directory as your code) which looks like:

[api]
email=cordelia@zulip.com
key=wlueAg7cQXqKpUgIaPP3dmF4vibZXal7
site=http://localhost:9991

Please remember to add this file to your .gitignore! Calling zulip({ zuliprc: 'zuliprc' } ) will read this file and then pass a configured zulip object to .then().

const zulip = require('zulip-js');
const path = require('path');
const zuliprc = path.resolve(__dirname, 'zuliprc');
zulip({ zuliprc }).then(zulip => {
  // The zulip object now contains the config from the zuliprc file
  zulip.streams.subscriptions.retrieve().then(res => {
    console.log(res);
  });
});

Examples

Please see some examples in the examples directory.

Also, to easily test an API endpoint while developing, you can run:

$ npm run build
$ npm run call <method> <endpoint> [optional: json_params] [optional: path to zuliprc file]
$ # For example:
$ npm run call GET /users/me
$ npm run call GET /users/me '' ~/path/to/my/zuliprc

Supported endpoints

We support the following endpoints and are striving to have complete coverage of the API. If you want to use some endpoint we do not support presently, you can directly call it as follows:

const params = {
  to: 'bot testing',
  type: 'stream',
  subject: 'Testing zulip-js',
  content: 'Something is horribly wrong....',
};

zulip.callEndpoint('/messages', 'POST', params);

Testing

Use npm test to run the tests.

Writing Tests

Currently, we have a simple testing framework which stubs our network requests and also allows us to test the input passed to it. This is what a sample test for an API endpoint looks like:

const chai = require('chai');
const users = require('../../lib/resources/users'); // File to test.
const common = require('../common'); // Common functions for tests.
chai.use(require('chai-as-promised'));

chai.should();

describe('Users', () => {
  it('should fetch users', () => {
    const params = {
      subject: 'test',
      content: 'sample test',
    };
    const validator = (url, options) => { // Function to test the network request parameters.
      url.should.equal(`${common.config.apiURL}/users`);
      Object.keys(options.body.data).length.should.equal(4);
      options.body.data.subject.should.equal(params.subject);
      options.body.data.content.should.equal(params.content);
    };
    const output = { // The data returned by the API in JSON format.
      already_subscribed: {},
      result: 'success',
    };
    const stubs = common.getStubs(validator, output); // Stub the network modules.
    users(common.config).retrieve(params).should.eventually.have.property('result', 'success'); // Function call.
    common.restoreStubs(stubs); // Restore the stubs.
  });
});

Each pull request should contain relevant tests as well as example usage.