Home

Importing Plumber

This example supposes the server is located at https://plmbr.herokuapp.com/. Please replace this with the proper URL for your server.

Import the plumber library:

<script src="https://plumberlib.com/plumber.js"></script>

Load a plumber client. Replace XXXXX with your API key and 'wss://plumberlib.com' with the correct URL for your server (use ws:// if you are not using https):

plumber.config({
    websocketURL: "wss://plumberlib.com",
    apiKey: "XXXXX"
});

API Keys

To get an API key, visit the plumber server (for example, https://plmbr.herokuapp.com/), register for an account, and log in. Visit the dashboard to find your API key.

Plumber Basics

Plumber allows programmers to create "pipes" that send and receive data to/from the plumber server. See the integrations page for examples of what you can do with pipes.

Creating Pipes

To create a pipe, call plumber.getPipe. This function will create a pipe if it doesn't exist or retrieve a pipe if it does exist. These calls should be made after calling plumber.config(). For example:

• pipe = plumber.getPipe('messages') gets a pipe named 'messages'
• pipe = plumber.getPipe() gets the "default" pipe (named 'default')
• The plumber object itself is also a pipe (the default pipe)

Subscribing to Pipes

To "listen" to pipe events, we need to "subscribe" to the pipe by calling pipe.subscribe (if pipe is a pipe):

const subscription = pipe.subscribe((data) => {
    console.log("new data", data);
});

To test the subscription, we can "shout" in the same pipe (either from this client or from another client:

pipe.shout("hello!");

This should print out "new data" {type: 'shout', data: 'hello!'} if you already called .subscribe

To unsubscribe from a pipe, call pipe.unsubscribe:

pipe.unsubscribe(subscription); // subscription is either the object returned from .subscribe or...
# the function itself (both should be the same object

Pushing Data to Pipes

There are several built-in methods for pushing data to pipes. A simple example is "shouting", which sends data to every object subscribed to the pipe. We can should by either calling:

pipe.shout(data); // data is the data you want to send to other clients

or by calling the "raw" .do method (.shout calls .do automatically):

pipe.do('shout', data);

Any time we push data do a pipe, the method will return a Promise, that resolves with the server's response.

For other things you can do, see the integrations page

Rate Limits

By default, our Plumber server has rate limits to prevent server abuse (if you want no rate limits, you can deploy your own server). By default, our rate limits are:

• No more than 100 requests per second
• No more than 10,000 requests per hour
• No more than 1,000,000 requests per day

Hitting any one of these limits will cause an error.