express-web-monetization

Express Web Monetization

Charge for resources and API calls with web monetization

• Overview
• Example Code
• Try it Out
  • Prerequisites
  • Install and Run
• API Docs
  • Constructor
  • Receiver
  • Paid

Overview

Using Interledger for payments, Web Monetization allows sites to monetize their traffic without being tied to an ad network. And because payments happen instantly, they can also be tracked on the server-side to unlock exclusive content or paywalls.

express-web-monetization makes this easy by providing middleware for your Express application. Charging your users is as easy as putting request.spend(100) in your route handler. No need to convince them to buy a subscription or donate.

Example Code

Below is an example of some of the functions that you would use to create paywalled content. For a complete and working example, look at the next section.

const express = require('express')
const app = express()
const server = require('http').Server(app)
const router = express.Router()
const { WebMonetizationMiddleware, ExpressWebMonetization } = require('express-web-monetization')
const monetizer = new ExpressWebMonetization()
const cookieParser = require('cookie-parser')

// This is the SPSP endpoint that lets you receive ILP payments.  Money that
// comes in is associated with the :id
router.get(monetizer.receiverEndpointUrl, monetizer.receive.bind(monetizer))

// This endpoint charges 100 units to the user with :id
// If awaitBalance is set to true, the call will stay open until the balance is sufficient. This is convenient
// for making sure that the call doesn't immediately fail when called on startup.
router.get('/content/', async (req, res) => {

  await req.awaitBalance(100)
  req.spend(100)
  // load content
})

router.get('/', async ctx => {
  // load index page
})

app.use(cookieParser())
app.use(WebMonetizationMiddleware(monetizer))
app.use('/', router)
server.listen(8080)

The client side code to support this is very simple too:

<script src="node_modules/express-web-monetization/client.js"></script>
<script>
  var monetizerClient = new MonetizerClient();
  monetizerClient.start()
    .then(function() {
      var img = document.createElement('img')
      var container = document.getElementById('container')
      img.src = '/content/'
      img.width = '600'
      container.appendChild(img)
    })
    .catch(function(error){
      console.log("Error", error);
    })
</script>

Try it out

This repo comes with an example server that you can run. It serves a page that has a single paywalled image on it. The server waits for money to come in and then shows the image.

Prerequisites

• You should be running Moneyd for Interledger payments. Local mode will work fine.

• Build and install the Minute extension. This adds Web Monetization support to your browser.

Install and Run

git clone https://github.com/andywong418/express-web-monetization.git
cd express-web-monetization
npm install
DEBUG=* node example/index.js

Now go to http://localhost:8080, and watch the server logs.

If you configured Minute and Moneyd correctly, you'll start to see that money is coming in. Once the user has paid 100 units, the example image will load on the page.

API Docs

Constructor

new ExpressWebMonetization(opts: Object | void): ExpressWebMonetization

Create a new ExpressWebMonetization instance.

• opts.plugin - Supply an ILP plugin. Defaults to using Moneyd.
• opts.maxBalance - The maximum balance that can be associated with any user. Defaults to Infinity.
• opts.receiveEndpointUrl - The endpoint in your Hapi route configuration that specifies where a user pays streams PSK packets to your site. Defaults to /__monetizer/{id} where {id} is the server generated ID (stored in the browser as a cookie).
• opts.cookieName - The cookie key name for your server generated payer ID. Defaults to __monetizer.
• opts.cookieOptions - Cookie configurations for Express. See Express response setting cookies options for more details! Only defaults are httpOnly: false

Receiver

instance.receiver(): Function

Returns a Express middleware for setting up Interledger payments with SPSP (used in Web Monetization).

Client constructor options

new MonetizerClient(opts: Object | void): MonetizerClient

Creates a new MonetizerClient instance.

• opts.url - The url of the server that is registering the HapiWebMonetization plugin. Defaults to new URL(window.location).origin
• opts.cookieName - The cookie key name that will be saved in your browser. Defaults to __monetizer. This MUST be the same has opts.cookieName in the server configuration.
• opts.receiverUrl - The endpoint where users of the site can start streaming packets via their browser extension or through the browser API. Defaults to opts.url + '__monetizer/:id' where id is the server generated payer ID. This MUST be the same has opts.receiverEndpointUrl in the server configuration.

Middleware for cookies

WebMonetizationMiddleware(monetizer: ExpressWebMonetization)

This middleware allows cookies to be generated (or just sent if already set) from the server to the client. It also injects the awaitBalance and spend methods described below. Note that your app must require and use the cookie-parser middleware before it uses the WebMonetizationMiddleware.

Charging users

The methods req.spend() and req.awaitBalance() are available to use inside handlers.

req.spend(amount): Function

Specifies how many units to charge the user.

req.awaitBalance(amount): Function

Waits until the user has sufficient balance to pay for specific content. awaitBalance can be useful for when a call is being done at page start. Rather than immediately failing because the user hasn't paid, the server will wait until the user has paid the specified price.