github  /  npm  /  documentation

@omaha/client

This is the official JavaScript client library for Omaha. It's fully typed, supports all standard endpoints and comes with a websocket client for optional event listening. Works in both browsers and server side applications. ✨

documentation

using a token

Provide an access token to start using the client immediately.

import { Omaha } from '@omaha/client';

const client = new Omaha('https://omaha.example.com', {
    token: 'dG9rZW4.CilV4Ntq5GsATtmtO4ZQM6HZIzN/1i+ffuZ12CoK0Bs'
});

logging into an account

Use the auth.login() function to log into the desired account. The client's token will automatically be updated so you can begin calling other endpoints immediately.

import { Omaha } from '@omaha/client';

const client = new Omaha('https://omaha.example.com');

await client.auth.login({
    email: '[email protected]',
    password: '12345678'
});

searching for releases

Easily get an array of releases that match your parameters.

await client.releases.search('repo_id', {
    constraint: '^2.0.0'
});

creating and publishing releases

First, create a new draft release with the target version. If there's another draft with the same version, it's treated as an update, so retrying any failed scripts will work.

await client.releases.create('repo_id', {
    version: '2.0.1',
    description: 'Optional changelog goes here.',
    tags: ['latest']
});

Then upload attachments to the new release. The following example uploads an attachment for the main asset which is the default asset for new repositories.

await client.attachments.upload('repo_id', '2.0.1', 'main', {
    content: '/path/to/file.zip'
});

Once all attachments have been uploaded, you can publish the release.

await client.releases.publish('repo_id', '2.0.1');

realtime

Invoke the ws.start() function to begin listening to realtime events. Once started, the client will maintain a constant connection to the websocket server so long as the client has an active token.

client.ws.start();

Each time a realtime connection is established, a repositories event will be transmitted with an array of all repositories (and their corresponding collaborations) that the current token has access to.

client.ws.on('repositories', repositories => { ... });

There are also standard events for connect, connect_error, and disconnect consistent with the underlying socket.io client. For a list of all available events, check the types within the server code.

You can stop the realtime client at any time with client.ws.stop().

release subscriptions

If you're looking to implement updates over the realtime client, subscriptions can be used to monitor for new publishes that match a given constraint, and will also receive the current version.

const sub = client.ws.subscribe('repo_id', '^1.0.0', release => {
    if (release && release.tags.includes('latest')) {
        if (release.version !== installedVersion) {
            // install it or something...
            sub.setConstraint('^' + release.version);
        }
    }
});

• The callback function will be invoked immediately with the current matching release.
• The callback won't be invoked with the same release multiple times (e.g. when reconnecting).
• The release argument can be undefined if there are no matches.
• The provided releases are guaranteed to be published.
• The releases are always sent with tags and attachments.

If you're no longer interested in a subscription, use sub.close(). Note that subscriptions persist between connections including when the realtime client is started and stopped manually.

errors

server-side errors

Endpoints will throw instances of HttpError from this package whenever a server-side error occurs. You can catch specific types of errors using their class names. These errors will always contain helpful messages that should be passed directly to the end user.

client-side errors

By default, the client will reattempt requests that fail due to a client-side error. This can be configured from the constructor options. You can also listen to events on the client to see when such errors occur and are recovered from.

After the error exceeds the reattempt limit, it is thrown back up to the caller. These will be plain error or DOMException objects from the native fetch() API.

aborting requests

You can abort all active requests on a client at any time using the abort() method. This will cause all requests to immediately throw an AbortError back up to their callers. You can do this multiple times on the same client over its lifetime.

client.abort();

derived clients

When working with front-end components, you may wish to create a clone of the client so as to split up any events and aborts. To do this, use the derive() method.

const clone = client.derive();

The newly returned instance will have the same token and options as the parent client. If the token changes in the parent client, it will also change in the derived instance. However, all events and aborts are mutually exclusive.

When you're done using the instance (such as when the front-end component is detached) simply invoke the dispose() method to abort all active requests and detach it from the parent instance for garbage collection.

Here's an example from within a svelte component:

const clone = client.derive();
const promise = clone.do.something();

onDestroy(() => clone.dispose());

Remember that aborted requests will throw an AbortError so make sure this won't cause any problems.

events

The client offers the following events that can be useful in some situations. Note that all events, except token, are local to the individual client (and do not propagate back to parent nor down to derived instances).

interface OmahaEvents {
    error: [error: Error];
    server_error: [error: HttpError];
    client_error: [error: Error, attempt: number, maxAttempts?: number];
    client_recovered: [attempts: number];
    token: [token?: string];
    loading_start: [];
    loading_stop: [];
}

license

MIT