# socketxp-ws-client

> SocketXP websocket client library for subscribing and receiving webhook notifications from online applications.

Latest version **0.0.2** (published 2020-05-18) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install socketxp-ws-client
pnpm add socketxp-ws-client
yarn add socketxp-ws-client
bun add socketxp-ws-client
```

## 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.0.2 |
| Published | 2020-05-18 |
| First published | 2020-05-17 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 56.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ganesh Velrajan |
| Maintainers | gvelrajan |
| Keywords | socketxp, websocket, webhooks, webhooks, proxy |

## Links

- npm: https://www.npmjs.com/package/socketxp-ws-client
- Repository: https://github.com/socketxp-com/socketxp-ws-client
- Homepage: https://github.com/socketxp-com/socketxp-ws-client#readme
- Issues: https://github.com/socketxp-com/socketxp-ws-client/issues
- npm.io page: https://npm.io/package/socketxp-ws-client

## Dependencies (4)

- [winston](https://npm.io/package/winston.md) ^3.2.1
- [@types/ws](https://npm.io/package/@types/ws.md) ^7.2.4
- [@types/node](https://npm.io/package/@types/node.md) ^14.0.1
- [typed-rest-client](https://npm.io/package/typed-rest-client.md) ^1.7.3

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.0.2 (latest) — 2020-05-18
- 0.0.1 — 2020-05-17

## README

<p align="center">
    <a href="https://www.socketxp.com" target="_blank"><img width="100"src="https://www.socketxp.com/wp-content/uploads/2019/06/socketxp-logo-darknavy.png"></a>
</p>


## Problem

Rest APIs leveraging HTTP protocol is the modern way of communicating between applications over the internet. Applications can communicate using a pull method or a push method.  The pull method is inefficient in that, the receiver application needs to continuously poll the sender application for any updates or notifications that awaits to be communicated.  The push method is efficient in that the receiver application registers a REST API with the sender application.  Whenever there is an update or notification that needs to be sent to the receiver application, the sender invokes the registered REST API with appropriate data.  This push method of REST API communication between applications is also called as webhooks.  

The problem with communicating using webhook push notifications is that some applications are online with public IP, while some are behind firewalls and NAT without any public IP.  Sometimes the application doesn't have an HTTP server implementation at all to handle the REST API.

## Solution

SocketXP WebSocket Client allows applications to receive webhooks without public IP, re-configuring NAT/firewall or even having a web server in the first place. It does this by creating a sercure WebSocket tunnel (SSL/TLS connection) to the SocketXP Cloud Gateway( an online reverse proxy tunneling gateway run as a freemium SaaS service).  SocketXP Cloud Gateway creates an unique public HTTP endpoint (URL) for each user.  The user can use this public HTTP endpoint (URL) to register with any online webhook sender applications.  The user application(webhook receiver), running in the local network behind firewall and NAT, could integrate with the SocketXP WebSocket Client library to receive the webhook notifications.  The user application need not implement any HTTP server to receive the webhook notifications. 

## Installation

```
npm i socketxp-ws-client
```

## Usage

To start using this library:

1. Retrieve your auth token from [SocketXP portal](https://portal.socketxp.com/#/authtoken). You will need to supply them to the library.
2. [Create a SocketXP webhook relay tunnel](https://my.webhookrelay.com/buckets) named 'nodered' and check what input URL did you get (should be something like: `https://webhooks.socketxp.com/...`). Input URL will be your own webhook inbox that you can supply to any sender application to send webhooks or any HTTP requests to.
3. Import the library into your application:

```javascript
var ws = require(`socketxp-ws-client`);

// handler function has to accept a JSON string and parse on its own
var handler = function (data) {
    console.log(data)
}

// create a client with specified authtoken from https://portal.socketxp.com/#/authtokens and any webhook tunnels that
// can be created here https://portal.socketxp.com/#/tunnels. Handler function is called whenever there's a new message
var client = new ws.SocketXPClient('your-auth-token', ['tunnel-1', 'tunnel-2'], handler)

// connect starts a websocket connection to SocketXP Cloud Gateway 
client.connect();
```

### Example application

Set token as an environment variable:

```bash
export SOCKETXP_TOKEN=[YOUR AUTH TOKEN]
```

```javascript
// app.js
var ws = require(`socketxp-ws-client`);

var authtoken = process.env.SOCKETXP_TOKEN;

var handler = function (data) {
    console.log(data)
}

var socketxp = function () {    
    var client = new ws.SocketXPClient(authtoken, ['nodered'], handler)
    client.connect();

    // do some work

    // disconnect whenever connection is no longer needed
   client.disconnect();
}

socketxp();
```

To run it:

```bash
node app.js
```

Now, whenever webhooks are sent to your public endpoint `https://webhooks.socketxp.com/<webhook-tunnel-name>`, they will be received inside your application. You can subscribe to multiple webhook tunnels. Each message will have a JSON string in the following format that you can parse:

```javascript
{
  "type": "webhook",             // event type
  "meta": {                      // webhook tunnels, input and output information 
    "webhook_tunnel_name": "my-webhook-tunnel-name",                                
    "input_name": "https://webhook.socketxp.com/my-webhook-tunnel-name",
    "output_destination": "http://localhost:8080"
  },
  "headers": {                   // request headers
    "Content-Type": [
      "application/json"
    ]
  },
  "query": "foo=bar",            // query (ie: /some-path?foo=bar)
  "body": "{\"hello\": \"world\"}", // request body
  "method": "POST"                // request method
}
```

---
_Source: https://npm.io/package/socketxp-ws-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._