# u-wave-api-v1

> HTTP API interface for üWave.

Latest version **0.3.0** (published 2017-08-25) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install u-wave-api-v1
pnpm add u-wave-api-v1
yarn add u-wave-api-v1
bun add u-wave-api-v1
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2017-08-25 |
| First published | 2016-12-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 4 |
| Dependencies | 22 |
| Known vulnerabilities | 0 (+21 in 4 direct dependencies) |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Sooyou |
| Maintainers | goto-bus-stop, waf |

## Links

- npm: https://www.npmjs.com/package/u-wave-api-v1
- Repository: https://github.com/u-wave/api-v1
- Homepage: https://github.com/u-wave/api-v1#readme
- Issues: https://github.com/u-wave/api-v1/issues
- npm.io page: https://npm.io/package/u-wave-api-v1

## Dependencies (22)

- [ms](https://npm.io/package/ms.md) ^2.0.0
- [qs](https://npm.io/package/qs.md) ^6.2.1
- [ws](https://npm.io/package/ws.md) ^3.0.0
- [clamp](https://npm.io/package/clamp.md) ^1.0.1
- [debug](https://npm.io/package/debug.md) ^3.0.0
- [lodash](https://npm.io/package/lodash.md) ^4.16.1
- [router](https://npm.io/package/router.md) ^1.1.4
- [ultron](https://npm.io/package/ultron.md) ^1.0.2
- [ioredis](https://npm.io/package/ioredis.md) ^3.0.0
- [request](https://npm.io/package/request.md) ^2.70.0
- [bcryptjs](https://npm.io/package/bcryptjs.md) ^2.4.3
- [bluebird](https://npm.io/package/bluebird.md) ^3.4.6
- [debounce](https://npm.io/package/debounce.md) ^1.0.0
- [array-find](https://npm.io/package/array-find.md) ^1.0.0
- [nodemailer](https://npm.io/package/nodemailer.md) ^2.3.2
- [body-parser](https://npm.io/package/body-parser.md) ^1.15.0
- [ratelimiter](https://npm.io/package/ratelimiter.md) ^3.0.2
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^7.1.9
- [random-string](https://npm.io/package/random-string.md) ^0.2.0
- [try-json-parse](https://npm.io/package/try-json-parse.md) ^1.0.0
- [is-empty-object](https://npm.io/package/is-empty-object.md) ^1.1.1
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) ^1.0.5

## Recent versions

- 0.3.0 (latest) — 2017-08-25
- 0.4.0-beta.1 (wlk) — 2017-10-01
- 0.2.2 — 2017-07-09
- 0.2.1 — 2017-06-21
- 0.2.0 — 2017-06-15
- 0.1.0 — 2016-12-30

## README

# u-wave-api-v1

REST API plugin for üWave, the collaborative listening platform.

[Getting Started](#getting-started) - [API](#api) - [Building](#contributing) -
[License](#license)

> Note: üWave is still under development. Particularly the `u-wave-core` and
> `u-wave-api-v1` modules will change a lot before the "official" 1.0.0 release.
> Make sure to always upgrade both of them at the same time.

## Getting Started

```
npm install u-wave-api-v1
```

The module exports a middleware that can be used with express-style HTTP request
handlers.

## API

### api = createWebApi(uwave, options={})

Creates a middleware for use with [Express][] or another such library. The first
parameter is a `u-wave-core` instance. Available options are:

 - `server` - An HTTP server instance. `u-wave-api-v1` uses WebSockets, and it
   needs an HTTP server to listen to for incoming WebSocket connections. An
   example for how to obtain this server from an Express app is shown below.
 - `socketPort` - The WebSocket server can also listen on its own port instead
   of attaching to the HTTP server. In that case, specify the port number here.
 - `secret` - A string or Buffer containing a secret used to encrypt
   authentication tokens. It's important that this is the same as the `secret`
   option passed to the core library.
 - `recaptcha` - If you want to force ReCaptcha validation on new registrations,
   pass an object with ReCaptcha options. The only available option is `secret`,
   which is the ReCaptcha secret obtained from the "Server-side integration"
   panel on your [ReCaptcha site admin page][recaptcha].
 - `mailTransport` - [nodemailer](https://nodemailer.com) SMTP options or a transport object,
   used to send password reset emails.

```js
import express from 'express';
import stubTransport from 'nodemailer-stub-transport';
import uwave from 'u-wave-core';
import createWebApi from 'u-wave-api-v1';

const app = express();
const server = app.listen();

const secret = fs.readFileSync('./secret.dat');

const uw = uwave({
  secret: secret,
});
const api = createWebApi(uw, {
  secret: secret, // Encryption secret
  server: server, // HTTP server
  recaptcha: { secret: 'AABBCC...' }, // Optional
  mailTransport: stubTransport(), // Optional
});

app.use('/v1', api);
```

### api.attachUwaveToRequest()

Returns a middleware that attaches the üWave core object and the üWave api-v1
object to the request. The `u-wave-core` instance will be available as
`req.uwave`, and the `u-wave-api-v1` instance will be available as
`req.uwaveApiV1`. This is useful if you want to access these objects in custom
routes, that are not in the `u-wave-api-v1` namespace. E.g.:

```js
app.use('/v1', api);

// A custom profile page.
app.get('/profile/:user', api.attachUwaveToRequest(), (req, res) => {
  const uwave = req.uwave;
  uwave.getUser(req.params.user).then((user) => {
    res.send(`<h1>Profile of user ${user.username}!</h1>`);
  });
});
```

## Contributing

### Building

The build step compiles the futuristic JavaScript that's used in this repository
to code that can be used in engines today, using Babel. To compile the code,
run:

```
npm run build
```

When developing, it might be useful to recompile automatically on changes
instead, using:

```
npm run watch
```

## License

[MIT][]

[recaptcha]: https://www.google.com/recaptcha/admin#list
[Express]: https://expressjs.com

[MIT]: ./LICENSE

---
_Source: https://npm.io/package/u-wave-api-v1 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._