Monetize.js: Event-driven library to manage and simulate Web Monetization
Tags: gftwhackathon, showdev, webdev, opensource
Published: 2020-05-21 23:33:24

My submission for [Grant For The Web Hackathon](https://dev.to/devteam/announcing-the-grant-for-the-web-hackathon-on-dev-3kd1)

## What I built

An event driven library that serves as a wrapper around Web Monetization API. Also, a monetization simulator has been built to support the library and make testing the monetization process extremely easy.

### Features

- Flexible pointers management (Static and Dynamic).
- Promise-like syntax to watch events.
- Customizable cycle-through list of pointers.
- Support probabilistic cycle-through list of pointers.
- Calculate the total amount grouped by currency.
- Powerful simulator that works without iframe or installed extension.

### Submission Category: 

Foundational Technology

## Demo

I've prepared a detailed README file on how to use the library alongside a set of handy [examples](https://github.com/sunchayn/monetize.js/tree/master/examples) for some common scenarios.

The following is a selection of some features provided by the library.

### Watcher API

You can simply start using static mode by manually adding the payment pointer to the head tag:

```html
<head>
...
<meta
    name="monetization"
    content="$wallet.example.com/alice"
>
...
</head>
```

Then in your code you can listen to different events using

```javascript
monetize.when('start').then((event) => {
    // Your event listener logic here.
});

monetize.when('progress').then((event) => {
    // Your event listener logic here.
});
```

*The provided API is Promise-like but it doesn't necessarily behave like a Promise. For instance `then` here will be called as long as the event is fired, unlike Promises.*

#### Use a dynamic pointer

By default, monetize.js will auto-detect the pointer already added to the page. Additionally, it provides a set of handy methods to work with dynamic pointers.

```javascript
const p = '$example/bob';

monetize.pointer(p).then((watcher) => {
    // monetizationstart event has been fired.

    watcher.when('progress').then((event) => {
        // Your event listener logic.
    });
});
```
#### Amount API

The following is a basic example on how to work with the total streamed amount and currency for a given pointer.

*Note: to use Amount API you must use one of the dynamic pointer methods like `pointer` or `pluck` etc.*

```javascript
const pointer = '$example';

monetize.pointer(pointer);

// Get the Raw amount sent.
const amount = monetize.amount.getPointerTotal(pointer);
// => output: 5258

// Or get the Formatted amount
const amount = monetize.amount.getPointerTotal(pointer, true);
// => output: 0.035

// Get the currency
const currency = monetize.amount.getPointerCurrency(pointer);
```

#### Select pointer from list

You can randomly select a pointer from a given Array by calling the `pluck` method.

```javascript
const pointers = [
    '$alice.example',
    '$connie.example',
    '$bob.example'
];

// Randomly pick a pointer.
monetize.pluck(pointers).then(...);

```

Passing an object to `pluck` method will make it switch to probability based mode.

```javascript
const pointers = {
  '$alice.example': 0.6,
  '$bob.example': 0.05,
  '$connie.example': 0.30,
};

// Randomly pick a pointer based on it's probability.
monetize.pluck(pointers).then(...);
```

#### Cycle-through
Sometimes picking a single pointer on page load isn't enough. For this case, you may consider using `cycle` and `probabilisticCycle` to cycle through a list of `pointers` for a given `timeout`.

```javascript
    // Signature
    cycle(pointers [, timeout [, callback]])

    const pointers = [
      '$wallet',
      '$wallet2',
      '$wallet3',
    ];

    monetize.cycle(pointers, 5000).then(...);
```

Using probabilistic approach

```javascript
    // Signature
    probabilisticCycle(pointers [, timeout])

    const pointers = [
      '$wallet',
      '$wallet2',
      '$wallet3',
    ];

    monetize.probabilisticCycle(pointers, 5000).then(...);
```

*This example is available in the [examples](https://github.com/sunchayn/monetize.js/tree/master/examples) directory.*

![Cycle through example](https://dev-to-uploads.s3.amazonaws.com/i/0vtto6da8ihcydq6qmps.gif)

## Simulator
Beside the core library, a powerful Web Monetization simulator is shipped. It does not require any extension or to be executed inside an iframe.

An example for the simulator in action.

![Simulator example](https://dev-to-uploads.s3.amazonaws.com/i/y6gv1kqn9ba8psgl0enp.gif)

More details and documentation can be found in the repository.

## Link to Code

Library code is hosted on Github with detailed description on how to setup and use.
{% github https://github.com/sunchayn/monetize.js %}

## Additional Resources/Info 

I've created a glitch project that hosts some example for the library.

{% glitch monetize-js-examples app %}

---

Thank you for passing by, feel free to leave your feedback or suggestion. Good luck everyone!