Home

Awesome

Web Monetization Receiver

Server-side library for advanced Web Monetization integrations

Overview

Lots of sites can benefit from Web Monetization. Most of the time, you can add a little bit of javascript that causes Web Monetization enabled users to donate to you (The scripts are available here).

Some sites might want to do more than this. For example, an image gallery might want to offer some images only to its Web Monetization enabled users. Or a video site might charge per second of video streamed.

This repository contains tools which aim to make these advanced integrations easier.

Examples

Run npm install in this repository's root, then follow the README of the example you want to run.

API

Monetizer

const { Monetizer } = require('web-monetization-receiver')
const monetizer = new Monetizer()

Creates a "Monetizer" that wraps an ILP/STREAM server and exposes an easy to use API.

You can use Monetizer to charge for different actions on your server using Web Monetization. It's best suited for web apps where your user is browsing your site and paying continuously with Web Monetization.

Parameters

Monetizer.koa

app.use(monetizer.koa())

Connects this Monetizer instance to a Koa app.

Parameters

Return

Monetizer.generateSPSPResponse

const jsonResponse = await monetizer.generateSPSPResponse(tag)

Returns an SPSP response that allows a client to pay us. If you're using the monetizer.koa() you don't need to call this function anywhere. If you're not using Koa, then return await monetizer.generateSPSPResponse(tag) for any request that has Accept of application/spsp4+json. The tag should be a cookie that identifies the user.

Parameters

Return

Monetizer.listen

await monetizer.listen()

Initializes the STREAM server of this Monetizer. If you use generateSPSPResponse then it will call this function automatically.

Parameters

Return

Monetizer.getBucket

const bucket = monetizer.getBucket(tag)

Gets a bucket associated with a given tag. If you're using the Koa middleware then on any route you can access ctx.webMonetization to access the current user's bucket (equivalent of monetizer.getBucket(ctx.cookie.get('webMonetization'))).

If no money has been paid into the bucket, you'll just get an empty bucket.

After a timeout (configurable via opts.buckets.timeout in the Monetizer constructor) any bucket that hasn't been used will be cleaned up.

Parameters

Return

Bucket

A bucket represents the payment received by the server from a specific user. You can use a bucket object to add/spend funds.

The bucket constructor shouldn't be called directly, instead you should get it from monetizer.getBucket (or from ctx.webMonetization if you're using Koa).

Bucket.fund

bucket.fund('1000')

This function adds the given number of units to the bucket. There usually is no reason to call this directly, because the Monetizer's SPSP server will automatically fund the necessary buckets whenever payments are received.

Parameters

Return

None

Bucket.spend

if (bucket.spend('300')) {
  return paidContent
} else {
  throw new Error('insufficient funds')
}

Subtracts funds from the bucket. Returns true if there were enough funds, and false otherwise.

Parameters

Return

Bucket.awaitBalance

await bucket.awaitBalance('1000')
console.log('user can spend 1000 units')

Waits until the user has accumulated a certain number of units in their bucket. This is useful for a web server where the client attempts to load all resources immediately but will take some time to pay for all of them (See Examples).

This represents an absolute amount. If you awaitBalance('1000') it waits for the user to have 1000 units total, not 1000 units more than they did when the function was called.

Parameters

Return

Bucket.awaitAndSpend

await bucket.awaitAndSpend('1000')
return paidContent

Combines awaitBalance and spend into an atomic operation. First the balance is awaited, and then it is spent. If the spend fails, the await is repeated.

Parameters

Return

Bucket.monetizeStream

const stream = fs.createReadStream('video.webm')
return bucket.monetizeStream(stream)

const stream = fs.createReadStream('video.webm')
return bucket.monetizeStream(stream, {
  freeBytes: 10000,
  costPerByte: (1 / 5000)
})

Turns a boring regular stream into a cool paid stream. Whenever a chunk of data is ready on the stream being read from, chunk.length * costPerByte units are subtracted from the bucket. If the bucket hasn't got sufficient funds, the read stream is paused. Once the bucket gets sufficient funds, the stream is resumed.

You can use freeBytes to send a certain amount of data upfront without requiring payment (useful for buffering video quickly). costPerByte lets you fine-tune how much payment bandwidth is required to keep up with the stream.

To see an example of usage, refer to the video example.

Parameters

Return

Payer

const payer = new Payer({
  streamOpts: {
    minExchangeRatePrecision: 2
  }
})

Creates a Payer object. A Payer can be used to efficiently pay out to many different SPSP receivers. It keeps connections to each of the receivers cached until they time out in order to minimize the amount of connection re-establishment.

Parameters

Return

Payer.pay

await payer.pay('$twitter.xrptipbot.com/interledger', '100')

Sends some money to a payment pointer. If a STREAM connection to this payment pointer already exists then the money is sent over that connection. If no STREAM connection to this payment pointer exists, then one is created.

If the STREAM connection does not exist and cannot be established then this function will reject.

Parameters

Returns