# @amazebot/rocket-rest

> Simple handlers for calling Rocket.Chat REST API endpoints.

Latest version **0.2.1** (published 2019-04-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @amazebot/rocket-rest
pnpm add @amazebot/rocket-rest
yarn add @amazebot/rocket-rest
bun add @amazebot/rocket-rest
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.1 |
| Published | 2019-04-21 |
| First published | 2018-12-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | > 8.0.0 |
| Dependencies | 5 |
| Unpacked size | 26.6 KB |
| Known vulnerabilities | 0 (+24 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Tim Kinnane |
| Maintainers | timkinnane |
| Keywords | rocket.chat, chat, chatops, messaging, CUI, typescript, API, REST |

## Links

- npm: https://www.npmjs.com/package/@amazebot/rocket-rest
- Repository: https://github.com/Amazebot/rocket-control
- Homepage: https://github.com/Amazebot/rocket-control/tree/master/packages/rest
- Issues: https://github.com/Amazebot/rocket-control/issues
- npm.io page: https://npm.io/package/@amazebot/rocket-rest

## Dependencies (5)

- [axios](https://npm.io/package/axios.md) ^0.18.0
- [@amazebot/config](https://npm.io/package/@amazebot/config.md) ^0.1.1
- [@amazebot/logger](https://npm.io/package/@amazebot/logger.md) ^0.1.1
- [@amazebot/rocket-sims](https://npm.io/package/@amazebot/rocket-sims.md) ^0.1.1
- [@amazebot/rocket-socket](https://npm.io/package/@amazebot/rocket-socket.md) ^0.1.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.2.1 (latest) — 2019-04-21
- 0.2.0 — 2019-02-27
- 0.1.0 — 2019-01-10
- 0.0.1 — 2018-12-11

## README

[control]: https://github.com/Amazebot/rocket-control
[config]: https://github.com/Amazebot/rocket-control#config
[axios]: https://github.com/axios/axios
[rest-docs]: https://rocket.chat/docs/developer-guides/rest-api/

# 🛏️ Rocket Rest
Simple helpers for calling Rocket.Chat REST API endpoints.

---

### Usage

See the main [Rocket Control README][control] for general configuration.

See [Rocket.Chat's REST API docs][rest-docs] for specific endpoint requirements.

Install the package.

```sh
yarn add @amazebot/rocket-rest
```

Import the API helpers.

Typescript / Babel:
```ts
import * as API from '@amazebot/rocket-rest'
```

Javascript
```js
const API = require('@amazebot/rocket-rest')
```

#### `.client([host])`

Defines the URL for subsequent API requests. Returns an [Axios][axios] client.

API requests can be sent without an explicit connection, using the environment
defaults from [environment configs][config]. It is called implicitly by all
requests, so it only needs to be called explicitly to set a new host, or one
that's different from the env defaults.

```ts
const local = await API.get('channels.list') // env url (default localhost)
API.client('https://my.live.server') // changes target of following requests
const live = await API.get('channels.list') // will request from my.live.server
```

#### `.login([credentials])` and `.logout()`

Login is required before making requests to any endpoints that need
authorisation. Refer to the [Rest API docs][rest-docs], but most do.

Credentials object can be undefined or: `{ username: string, password: string }`

Login without credentials will use defaults from [environment configs][config].

```ts
API.login({ username: 'admin', password: 'pass' })
```

#### `.loggedIn`

Property contains a boolean of the login status.

#### `.request(method, endpoint[, data, auth, ignore])`

Make a request to your Rocket.Chat instance API.

**Endpoint** appended to the client URL, with `/api/v1` included.
**Method** can be `'POST' | 'GET' | 'PUT' | 'DELETE'`
**Data** can be an object to post or convert to query params for get requests.
**Auth** is a boolean to set if the endpoint requires auth (default true).
**Ignore** optional RegExp for expected error messages to prevent throwing.

```ts
// basic server info does not require auth
await API.request('GET', 'info', {}, false)

// get auth and request user list with query params
await API.login()
const users = await API.request('GET', 'users.list', {
  fields: { 'username': 1 },
  query: { type: { $in: ['user'] } }
})
```

#### `.get(endpoint[, data, auth, ignore])`

Proxy for `.request('GET', ...arguments)`

#### `.post(endpoint[, data, auth, ignore])`

Proxy for `.request('POST', ...arguments)`

#### `.put(endpoint[, data, auth, ignore])`

Proxy for `.request('PUT', ...arguments)`

#### `.del(endpoint[, data, auth, ignore])`

Proxy for `.request('DELETE', ...arguments)`

---
_Source: https://npm.io/package/@amazebot/rocket-rest · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._