Programmatic usage

The package exports the Client class, a Socket.IO client for the Hailer API.

const { Client } = require('@hailer/cli');
// or: import { Client } from '@hailer/cli';

Connecting

Client.create(options) connects and resolves to a ready client:

const client = await Client.create({
    host: 'https://api.hailer.com',
    username: 'you@example.com',
    password: 'set-this',
});

Whenever you can, prefer a user API key over embedding a password. Create one with v3.userApiKey.create. It is sent as the authorization header and needs no login call:

const client = await Client.create({
    userApiKey: 'userapikey_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy',
});

Options

Option	Description
username	Email address. Logs in automatically when password is also set
password	Password
userApiKey	User API key, an alternative to username and password
host	Backend server. Defaults to api.hailer.com. https:// is assumed if no protocol is given
rejectUnauthorized	Reject invalid SSL certificates. Defaults to true

Making requests

client.request(op, args) calls an endpoint by name with an array of positional arguments and returns a promise. Every endpoint, its parameters, and its return shape are documented in the endpoint reference:

const state = await client.request('v2.core.init', [['user']]);
console.log('Connected as:', state.user.email);

On failure the promise rejects with the Hailer error object.

Signals and events

Client is an EventEmitter:

Event	Description
signals	Real-time signal from Hailer, emitted as [name, meta]
connect	Socket connected
disconnect	Socket disconnected, with the reason
reconnect	Socket reconnected. The session is resumed automatically
error	Socket error

client.on('signals', ([name, meta]) => {
    console.log('Signal:', name, meta);
});

Sessions

After login client.sessionKey holds the session key. It is the same value as the hlrkey header used for HTTP requests. client.resume(sessionKey) resumes an existing session instead of logging in.

File uploads

Both resolve to the uploaded file's id:

const fileId = await client.uploadFileByName('./photo.jpg');
const fileId2 = await client.uploadFileStream(readableStream, 'photo.jpg');

Disconnecting

client.disconnect() closes the socket. Without it the process keeps running, since the client listens for signals.

Complete example

Create a wall post and log every incoming signal:

const { Client } = require('@hailer/cli');

(async () => {
    const client = await Client.create({
        host: 'https://api.hailer.com',
        username: 'set-this',
        password: 'set-this',
    });

    client.on('signals', ([name, meta]) => {
        console.log('Signal:', name, meta);
    });

    const post = await client.request('wall2.new_post', [{ subject: 'This is a wall post.', text: 'The content of my post' }]);
    console.log('Post created:', post);

    client.disconnect();
})();