The Interledger Community 🌱: Qwyre

'Empathy' - new African speculative fiction by Cheryl Ntumy on Qwyre.com

Gavin Chait — Mon, 09 Jan 2023 08:24:07 +0000

Qwyre is starting 2023 with the release of Empathy, a new work of African speculative fiction by Ghanaian writer, Cheryl Ntumy.

In Empathy, a mother tries to save her son from himself in this haunting tale set at the brutal intersection of alien intelligence and humanity.

Cheryl's work is monetised and you can read it here.

Qwyre is a streaming payments platform for collaborative publishing, and an ereader, and received a grant from the Interledger Foundation. Tap left or right on the page to go forwards or back.

Qwyre.com - What we learned, and our ethical foundations and plans for future development [Grant Report #2]

Gavin Chait — Tue, 29 Mar 2022 09:19:02 +0000

I'll be sharing these experiences during April's Grant for the Web Community Call. Please come along and let me know what you think.

Register here for the Grant for the Web Project Skill Share Community Event 10am EST / 4pm CEST on Monday 25 April

Streaming micropayments - web monetization - is new. And the online new is no longer absorbed into society with the unquestioning rapture of the 1990s. Neither should it.

From cryptocurrency pump and dump fraud to wildly hyperbolic promises to the tech industry's complicity in genocide ... there are many reasons for the average person to be sceptical of the new.

So, while the technical challenges are great, the social ones - of building trust, resilience, and engagement - are even greater.

Yet the promise of disintermediated micropayments is greater still. It is up to us, the community of web monetization makers, to earn that trust.

What follows may seem unduly negative, but it helps to take stock. To have a realistic appraisal of what challenges us as we take our first tentative steps in this new medium. And, mostly, for me to recognise what I got right, wrong, and still have to reckon with.

Makers are not speculators. Risk is not theirs to take.

I used to run a small development project in the shanty towns around the formal neighborhoods of Cape Town. An ubiquitous feature of every street are tiny spaza kiosks selling small packets of sugar, soap, coffee or whatever, repackaged from much larger boxes. What is in those packets isn't some no-name brand, cheapest of the cheap. Nope. Brands. Omo. Lux. Five Roses. Hulett. All the comforting South African logos.

For a simple reason.

When you are poor you have no room for risk. Too much goes wrong on a daily basis for which you have no protection. You cannot afford to buy the wrong brand of soap.

Creators on the internet may not be quite as poor, but they're on the cusp. Most are not superstars, but have multiple sources of income, cross-subsidising their creative pursuits with whatever ad hoc work they can take. Setting up Qwyre.com and telling authors, "Hey, come publish here, you'll get paid in real-time and direct to your payment pointer." isn't a quick win.

Sampling the writing community yielded responses like, "Cryptocurrency? Hell no!"

It doesn't matter that publishing on Qwyre is simpler than publishing on Amazon, there is no halo effect from established brands. Payments aren't via Visa or Mastercard. Creators can't use their own credit cards, Stripe or PayPal accounts.

Instead, creators have to sign up for a whole new "wallet" and generate a "pointer" on a web service replete with promotion of speculative cryptocurrency investment.

It certainly helps that Uphold and Gatehub are working on complying with regulatory authorities in the US and EU, but that takes time. It's also happening now, so when people do go to sign up, they're sometimes told that new accounts aren't available in their region while this regulatory process unfolds.

Lessons: I made the technical process of uploading creative work and publishing as easy as possible, but payment pointers and getting paid are - like most publishing platforms - not part of the core workflow. It's not a technical challenge, but a critical part of their user experience.

I will be redeveloping the publishing experience to integrate payment information and ensure writers know I take their getting paid as equal to them publishing and being read.

Making monopolised proprietary lock-in impossible

The tech industry has awoken to new EU legislation which mandates prying open the locked-down world of text apps, like WhatsApp. Such lockin should never have been tolerated in the first place, and a world in which the underlying technology had been designed around open interoperability protocols wouldn't have supported tech monopolies in quite the same way, or caused such pandemonium when eventually dismantled. After all, we take it for granted you can phone anyone on any network.

But just because we came up with a new way to support micropayments doesn't mean we haven't stored up a future where a small number of companies monopolise monetization.

As Eric Parker, South African franchise guru and co-founder of Nandos, used to say, "Run your small company as if you were a big company."

He didn't mean "exploit your workers, offshore your profits, and lobby politicians". What he was talking about was technical and management debt. That the mistakes you make in the early days become part of the foundation of your company and impossible to remove later on. They will hurt you forever, and most are avoidable. If you hire only white males from the same schools at the beginning, and twenty years later you wonder how you have fomented a bro-led toxic culture hostile to women and diversity, you're being deliberately ignorant of the world around you.

To summarise the summary: Start as you mean to go on.

In our case that means make monopolies impossible from the beginning. Don't give yourself the option. Make it easy for your users to leave. Let them take their stuff and go whenever they want.

I can't do much about how Coil, Uphold or Gatehub may choose to run their businesses, for good or ill. But I can control my own.

That means make leaving easy. Creators must be able to take their work - their epubs - and publish them elsewhere. There must never be the option for me to centralise payments. Creators must always be paid direct. But these are relatively easy. There's harder stuff on interoperability I'm not sure how to solve:

If you have a successful link to your work, how do you take that with you? Probably impossible, unless I figure out how authors can use their own domain names?
What happens if someone already has their own website but wants to integrate with mine for search and reading interface, is that possible?
What about other platforms doing the same thing? Should we have shared APIs and expose each other's work? Should a reader on Qwyre be able to read a work on my platform on a different app?

If you think about Amazon, or Spotify, your library isn't available on other platforms. Even when you outright buy the work, you're locked in to reading or listening on their app. I have multiple copies of some things simply because of this lack of interoperability. And it's not right.

Lessons: It's easy to get lost in the technical challenge of making interoperability work, but that's to lose sight of needing to have enough readers and creators to make this necessary in the first place. Start as you mean to go on doesn't mean do it now.

So ... this is a commitment to making interoperability core to Qwyre - to using open standards (like epub and not inventing some alternative locked-down mobi standard instead) - but not to be so obsessed with this that it overwhelms a primary need to build a community of happy readers and creators in the first place.

Crucially, it is also to be a vocal champion against monopolies, and for open interoperability. To be mindful of what I make, and what I do, to ensure I am in accord with these standards.

Patience and the new

One challenge of engaging with tech-driven innovation is watching the wave lift boats all around you, but not yours. Too early, too late, not in the right place ... you end up obsessively running weird - and unnecessary - A/B testing. What about this colour? If the button was 2mm higher on the page? How about a different font?

Before we had the monopoly stacks, I remember grazing widely on search engines and news portals. We certainly have a winner-takes-all problem, but see my previous point.

It will take time to build confidence. Time for the various tech components to mature. Time to become part of the world.

So, what should you be doing in the absence of users. What should I be doing in the absence of readers and creators?

I'm running a short-story competition although the pushback from communities where I've sought to promote it has been weird. It's not ok to promote it because of the payments process. Promoting writers to publish because they will get paid by readers while they read is, somehow, not acceptable, but charging readers for a published work and not paying the writer a live share of that is traditional and acceptable.

Until monetization becomes as mainstream as credit cards, it's going to be difficult for it to be an innocuous and inoffensive way of simply getting paid.

So, however long it takes to attract other writers and readers is going to take patience. Whether I like it or not doesn't enter into it.

But ... I am a writer. I can write for my own platform, and that will help me improve the app in measurable ways that make writing and publishing more pleasing for others.

You can see my doing that now. Here's a short story called "If only they couldn't talk". Go ahead. It's free. You don't even need to enable monetization to read it.

Similarly, I need to engage, as much as this navel-gazing introvert is capable of.

Lessons: It's easy to over-think slow-uptake as indicative of commercial failure, but in a new industry - where so many of the concepts and technology are still very immature - it may simply be that you're too early. Spending emotional and financial bandwidth leaping about trying different things may leave you burned-out and spent.

It is better to have a consistent plan, one that fits within the limits of your mental and financial health, and keep going. There are certainly examples of overnight wonders, but there are just as many of plodders who got there slow and steady.

I commit to writing more, promoting more (but not obsessing about likes or hits ... I'm not particularly good at social media), and using the awesome thing I made.

Being supported by Grant for the Web has been an amazing and creative experience. I've enjoyed the community, feedback, and support from the team. I know this is only the beginning, and I hope the alumni of these first few years get to gather in a few years time and look back in wonder and gratitude at all we achieved.

Good luck, and go read something (on Qwyre.com).

Qwyre launches its first web-monetized African speculative fiction short-story competition

Gavin Chait — Tue, 22 Mar 2022 14:57:12 +0000

African speculative fiction is finally achieving recognition. Nnedi Okorafor and Tade Thompson have won all the awards. All of them. And amazing anthologies like Dominion edited by Oghenechovwe Donald Ekpeki and Zelda Knight have introduced some amazing authors, like Dilman Dila and Mame Bougouma Diene, to a wider audience.

We can do more.

Qwyre.com is live and we want to showcase awesome writers while also promoting web monetization for authors.

We are offering $50 to each of the ten best African speculative fiction short-stories published on Qwyre.com by 30 April 2022.

The rules are simple:

5,000 words, but if your story works longer or shorter, do that. Don't let a word count get in the way of a good story.
Competition only open to African speculative fiction.
Multiple submissions are fine, but you can only win for one.
Original is preferred but – if you have rights to republish – a second publication is ok. This is especially welcomed if you've self-published elsewhere.
Abide by Qwyre's rules.

Most fiction competitions end there, with the prize. But Qwyre can offer everyone - including those who aren't amongst the ten - the opportunity to earn direct from readers from the moment they're published.

Web monetized work earns about 36 cents per hour, or 0.6 cents per minute. For every minute someone reads your work on Qwyre, you get paid.

To put this in perspective, streaming music services pay about 0.003 to 0.12 cents per 5-minute song. A 5,000 word short-story would take about 12 minutes to read and earn 7.2 cents. You need to be read 700 times to earn $50.

Qwyre authors share in this income directly and in real time.

If you've self-published on Amazon, you know how their approach works. They take all the money and, some interminable time later, they pay you your share. Web monetization means you get paid in real time. Instead of us taking the money, calculating shares, and sending to different people, we divert payments to parties as people read.

If you agree to pay an editor 15%, and 85% for yourself, then there is a three-way split: 12:73:15 (this ratio takes into account Qwyre's 15% share). Web monetization is per-second payments, and we push payments to each party in this agreed ratio. Everyone gets paid right away.

Which means - just like other publishing platforms - you need to create an account so you can be paid.

Here's how all this works ...

Publishing your work on Qwyre.com

First things first. Open your veins and bleed. Write something. Once you have something written, proceed.

Prepare your work for publication

There are plenty of ways independent authors can self-publish. That lack of any friction between the author and the reader is one reason so much is produced, and with such low quality. Commercially-published work benefits from the simple barrier of being edited. Just that surfaces poor prose and obscure, or irrational, storytelling.

Qwyre is about collaborative publication, so here's the workflow:

1. Start at your new creator's workshop

Here you'll find links to the docx convertor, as well as panels to review your works in progress, and offers for editors.

2. Convert your Word document docx to an epub, in a three step process where you'll describe your work (title, author, publishing date, keywords, that sort of thing ...), upload the document and cover, and then build the standards-compliant epub. This allows Qwyre to stream your work to readers.

3. Import your epub, either during the docx conversion process or, if you've produced your epub in some other way, direct into the platform:

This is intended to be as easy as possible. If you've got an external link or a local file, either can be imported.

4. Review your work and check that metadata (your descriptions and keywords), the contents and sample text are presented as expected:

The metadata and text are derived entirely from the epub you uploaded. If anything is incorrect it may be because of non-conformance to the epub standard, or because the text is wrong in the source. Correct that, upload a new epub, and ensure you're happy.

4. Prepare a contract with your revenue share between yourself and prospective editors. This is what will be shared between the author and editor during monetization.

Anyone can be an editor and I encourage writers to offer to edit other writers work. Not only does this help you improve as a writer, but you also have the opportunity to share in the revenue of a greater diversity of work. Editors are paid too!

5. Offline collaboration for publication is an important part of the creative process.

The review and collaboration process is initiated via email. Sharing the editor's email address with the author only when offered, and then getting out of their way once they finalise their contract. Qwyre is not going to own the editorial process and the parties to the creative work should edit and review as they prefer.

Only once both parties have agreed the contract, and agreed the work is ready for publication, can the creator release the work onto the platform.

6. Set up your payment pointer

You can't use your credit card and need a dedicated payment pointer to start receiving streaming payments. This is straightforward and well-described here Digital Wallet and Payment Pointers for each of the current wallet providers:

Once you have your pointer, simply save it to your personal profile.

You're ready to be read!

7. Readers can search for published works and start streaming

There is as little friction between reader and reading as possible. You don't need to login to start reading a work. You don't even need to pay for the initial pages. The app works for free, giving a reader the opportunity to anonymously try out the app, and your creative work.

A call to readers and writers

So ... there it is. I created Qwyre in part because of my frustration with app-based self-publishing services and my desire to read more African speculative fiction.

I you can write, please write. If you can edit, please edit. And if you can't do either, help me get this message out!

If you have any questions or concerns email me, or drop a comment in the chat. I would love your help in spreading the word and helping to draw out writers to Qwyre and web monetization. And I hope, soon, to be reading your work.

Qwyre.com — Converting a digital work into a monetized stream [Grant Report #1]

Gavin Chait — Mon, 03 Jan 2022 18:04:55 +0000

Projects are like London buses. You wait for hours, standing alone in the pouring rain at midnight freezing your important bits and wondering if you'll ever be warm again, when two come along together.

And so I found myself, six months ago, navigating two wonderful projects while hoping that I'd pull it off.

Gentle reader. Working 14-hour days, seven days a week, for six months, is not a healthy pursuit. Hence the break in these monthly reports. My apologies. But the last month has been well spent with an interim release for you to play with.

One of the most gratifying new features (for me, as a lazy person) is that you can paste a link to an epub and simply import direct into the app. And here a shout-out to Standard eBooks which are a wonderful community project reformatting public domain books into standards-compliant epubs.

If you're a self-published author and want to link to the app direct and don't want your readers to have to faff about, generate a link yourself:

Converting digital objects into digital streams

Web Monetization is a per-second payment stream and it requires a per-second product. Some things are naturals for this, and they're usually live or where the digital service is tightly linked to a platform. Text isn't normally streamed, but music and movies can easily be downloaded as well.

Streaming means deliberately breaking data into chunks and streaming those in a format that permits live, iterative, building of the digital object from these chunks while also serving the content in that dynamic object.

For text, that means a stream of words. Except they also have to carry markup so they're formatted properly on arrival. Then the page needs to be updated without offending the reader. It's not trivial.

For anyone else stuck with this, here is an exceptional Stackoverflow answer that details not just the high-level strategy, but also provides a great foundation in code.

Progress on objectives

The status as of the previous updates (1, 2, 3):

Convert docx into epub using Chapisha,
Read epub using Futurepress,
Monetize using Coil (and please do read my lengthy write-up on how to do this).

For this report, these additional features are complete:

Importing an *epub" for publication,
Agreeing, and signing, a contract with an editor,
Converting a work to a stream source,
Streaming the work in response to web monetization.

Preparation of a work for publication

There are plenty of ways independent authors can self-publish. That lack of any friction between the author and the reader is one reason so much is produced, and with such low quality. Commercially-published work benefits from the simple barrier of being edited. Just that surfaces poor prose and obscure, or irrational, storytelling.

Qwyre is about collaborative publication, so here's the workflow:

1. Start at your new creator's workshop

Here you'll find links to the docx convertor, as well as panels to review your works in progress, and offers for editors.

2. Import your epub, either during the docx conversion process or, if you've produced your epub in some other way, direct into the platform:

This is intended to be as easy as possible. If you've got an external link or a local file, either can be imported.

3. Review the work and check that metadata, the contents and sample text are presented as expected:

4. Prepare a contract with your revenue share between yourself and prospective editors. This is what will be shared between the author and editor during monetization.

Here's another reason to only permit publication after review by an editor. Here I'm attempting to claim authorship of 'The Magician' by W. Somerset Maugham. No, that should never be accepted. Any editor should catch that right away and refuse even to accept an offer to collaborate on the work in the first place.

5. Offline collaboration for publication is an important part of the creative process.

Only once both parties have agreed the contract, and agreed the work is ready for publication, can the creator release the work onto the platform.

6. Readers can search for published works and start streaming

7. Seamless call to monetization, and a judgement call ...

The sign-up process involves two steps:

Creating a Qwyre.com account
Creating a Coil.com subscription and linking that to Qwyre.com

One reason was to physically seperate Qwyre.com from monetization. The app itself stores nothing about monetization out of the browser. There's no account to delete or concern about data probity. Sure, not forcing the user to create an account would simplify sign-up. That way we only have to worry about the reader signing up with Coil.

However ... I need some way to keep track of where the reader has gotten to in streaming any work so that they are not double-charged for the same thing across multiple devices. That requires a login.

Once the reader has authenticated everything, they are still in complete control of the monetization process.

Development and monetization receipts ...

This is harder than it needs to be. There are no development APIs, so you're working with live Coil accounts, and the largest challenge is proving that you are getting paid.

Webmonetization offers a receipt verifier service. This is yet another third-party layer between your app and payment. Instead of embedding wallet pointers into your code, you now interpose a verifier endpoint: $receipt-verifier.example/%24wallet.example%2Falice

It's a complex requirement and immediately runs into CORS issues, meaning you'll need to implement this all yourself creating additional opportunities for broken/dangerous code.

Some recommendations I'd like to see:

We need some developer endpoints. I want to test out what happens when payments fail in various scenarios. This is hard to do with a live account.
The Web Monetization scripts returns a series of events. It would be tremendous if this included a receipt by default. If I want to implement my own receipts verifier, fine, but not having it here creates sequencing issues. Receipts need to be verified continuously for continuous payments. The more endpoints to pole, the more chance for glitches and delays.

What's next?

The last outstanding feature is the search engine. Once that is done, I'll release the final version. I also intend to run a demo with the African Speculative Fiction Society members and get some feedback on the work to date. The 2021 Nommo Awards were just announced so go find some African scifi to read.

What community support would benefit your project?

I'd appreciate thoughts and feedback on the publication workflow, as well as on the interim release at Qwyre.com.

Qwyre.com - A guide for integrating Coil & Web Monetization APIs for creatives doing the job once

Gavin Chait — Fri, 03 Sep 2021 17:46:05 +0000

There are two principle types of developer: journeymen and creatives. A journeyman gains experience through repetition. Overly-technical or complex documentation isn't a problem since the journeyman uses it more like landmarks. The creative coder is developing software as a means to express their idea. They know where they want to go but are covering the ground once.

This guide for integrating Coil & Web Monetization APIs is written for creatives.

Why implement the API? It is your responsibility - as creative - to ensure that your prospective subscribers and supporters can easily, and quickly, i) understand what it is that you are offering, and ii) pay for it in a way that is easy and doesn't scare them. You cannot rely on them to install a browser plugin for a technology they may never have heard of.

There is a secondary reason ... the API offers you more flexibility and creativity in what you can offer. It is more expressive.

Notes to the guide

Approach

The first step is to have a high-level understanding of exactly what needs to happen to authenticate a subscriber and authorise web monetization. This may feel like repetition, but that means we go through this twice. First to get a broad understanding, then into the technical detail and gotchas.

I recommend you follow along in the reference documentation (see References at the end), and this guide. This guide compliments the documentation and is not a substitute for it.

Development stack

I make the assumption you know how to code and that you know enough about best-practice in app development that I won't need to include everything. I provide most code required for implementation, but the tech stack is very specific:

Nuxt.js - A Vue.js framework, based on Node.js, for the Progressive Web App frontend,
FastAPI - A Python framework for building APIs, for the server backend.

The coding languages are TypeScript and Python with annotations (specifically Pydantic). These annotations ensure code consistency and reduce the number of gotchas.

The complete development stack is available as a Docker Compose base project generator:

whythawk / full-stack-fastapi-postgresql

Full stack, modern web application generator. Using FastAPI, PostgreSQL as database, Nuxt3, Docker, automatic HTTPS and more.

Gotchas

There are a LOT of gotchas. These will be presented as:

GOTCHA: a gotcha is an easy-to-miss detail, which - once overlooked - will cause you hours / days of lost time.

Consider this a first draft, and please do respond in the comments below if anything is unclear, or you see a better / more efficient way of doing things.

Let's get started.

Web Monetization is about `authentication` and `authorisation`

Your app is in the middle between your subscribers and Coil as monetization provider. Your objectives are authentication - prove who you are - and authorisation - prove you have authority to perform an action.

Your app needs to perform each of these tasks with each party.
You need to tool up your app so that it has the necessary credentials and scripts to perform these tasks.

There are four separate components you'll need to build:

Authenticate your app with Coil: you'll do this once for each app - a minimum of twice, for your development and production environments, and is largely a manual process with application via email and an online form,
Embed the OAuth Web Monetization (OWM) script in your app: again, once, as you develop your app,
Your subscriber authenticates your rights to their monetisation account: for each new subscriber,
Your subscriber authorises your right to monetize your content: for each subscriber, every time they permit monetization, and refreshed every 30 minutes.

This is how your subscriber will experience the process:

1. They visit your app

2. They decide to authorise your app to receive payments and click on a link you generate

3. They are referred to Coil where they must approve authentication.

4. Coil refers the subscriber back to a specific receiving page where your app needs to process the token it receives and authenticate.

5. Your app updates the subscriber and invites them to begin streaming.

Only one of these steps requires your subscriber to leave your app and make an active authentication decision. Thereafter, how you decide to start and stop monetization is up to you.

Now for the technical details.

1. Authenticate your app with Coil

At the end of this process you will have:

client_id,

client_secret converted to base64.

This is a strictly manual process and takes some time. Do it earlier rather than later.

Follow Coil's documentation to register your developer account, and email devs@coil.com,
It is normal to wait a week or more for them to respond, when they do, you will be able to register apps and request authentication tokens,

https://coil.com/oauth_register
- Client app name: qwyre-local
- Redirect URIs (comma-separated): https://localhost:3000, https://localhost:3000/support-us
- Logo URI: https://localhost:3000/qwyre-logo.svg
Make a note of the app registration details as they are not listed anywhere afterwards, and you must have them exact for the next step.

GOTCHA: before you decide on the redirect URI pause to think. This URI will become the most important page in managing this process, and it may not work for you if that page is root.

Once you receive your app authentication token from Coil, you will need to register with Coil's Open ID Connect (OIDC) provider to exchange the token for a client ID and client secret. You can do this from a bash command line.

Coil's documentation is relatively straightforward. Dig out the app registration terms you used above:

request:

curl -X POST https://coil.com/oauth/reg \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Pb8w98v18ikkZyy26nxXK5OKDDsN6kfEJVmQ2id9tbC' \
  -d \
  '{
    "redirect_uris":["http://localhost:3000","http://localhost:3000/support-us"],
    "client_name": "qwyre-local",
    "tos_uri": "https://localhost:3000/privacy/",
    "policy_uri": "https://localhost:3000/privacy/",
    "logo_uri": "http://localhost:3000/qwyre-logo.svg"
  }'

GOTCHA: tos_uri and policy_uri must be https otherwise the request will fail. It doesn't matter whether your development environment is not certified (although you can issue yourself a self-signed certificate if you like). The end-points are not tested, only the form of the URI.

response:

{
  "client_id": "314ac134-fc3c-4d28-bf43-ccb75a2f9fb2",
  "client_secret": "uVE2t7y1QvyM78PlBA3aQAUh6syXVw7P2XBr4QDsS2yrkETR6al9YFpH4NDloXh5",
}

This is abbreviated, and is the only time you'll get this, so save these details somewhere safe. These are the only two keys you need (for now): client_id and client_secret.

GOTCHA: Not really a gotcha, since it's clearly flagged in the docs, however, before you can use your client_secret, you need to make the string web-safe since you will be sending this in your first GET request. That requires converting it to base 64. In Python, that's pretty easy:

import base64
base64.b64encode(bytes(client_secret, 'utf-8'))

Then use that string as your client_secret.

2. Embed the OAuth Web Monetization (OWM) script in your app

At the end of this process you will have:

Embedded Coil's OWM script in your app.

Coil describes this as a relatively straightforward process. It is not.

GOTCHA: the Coil OWM script does not play well with Nuxt.js and, I'm assuming, any Node-based JavaScript/TypeScript framework that performs server-side-rendering and hydration. If you don't know what this means, just be aware that this process is the source of many gotchas, not just when implementing web monetization.

Coil recommends you create a base index.html file as follows:

<html>
  <head>
    <meta name="monetization" content="$wallet.example.com/~alice">
    <script>
      if (document.monetization) {
        document.monetizationExtensionInstalled = true
      } else {
        document.monetization = document.createElement('div')
        document.monetization.state = 'stopped'
      }
    </script>
    <script src="https://cdn.coil.com/coil-oauth-wm.v7.beta.js" defer>
    </script>
  </head>
  <body>
    <p>Testing web monetization via coil polyfill using btp token.</p>
    <script>
      document.coilMonetizationPolyfill.init({ btpToken: 'e0y1...' })
    </script>
  </body>
</html>

You'll notice three important components:

The meta tag with the destination wallet for streaming payments,
A script tag with defer import of the OWM script,
And an if else statement setting up the div for interacting with document.monetization.

Something that I spent quite a bit of time frustrated by is that I couldn't interact with the OWM script in any way until after it had been initialised by creating that seemingly innocuous div. This has implications for the way Node interacts with the script.

The recommended way to include external / third-party scripts in Node is via a config.js file. For example:

// Global page headers: https://go.nuxtjs.dev/config-head
// https://vue-meta.nuxtjs.org/api/#script
// https://javascript.info/script-async-defer
head: {
    title: "Qwyre",
    meta: [
      { charset: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1" },
      { name: "monetization", content: process.env.COIL_PAYMENT_POINTER },
      { hid: "description", name: "description", content: "" },
      { src: "https://cdn.coil.com/coil-oauth-wm.v7.beta.js", defer: true },
    ],
    link: [{ rel: "icon", type: "image/x-icon", href: "/favicon.ico" }],
}

Then you would initialise the script in your layout (base html templates to structure any pages). This does not work.

At this time, you need to bypass Node/Nuxt.js and initialise your app.html (ordinarily not customised, and left to the framework to manage):

    <!DOCTYPE html>
    <html {{ HTML_ATTRS }}>
      <head {{ HEAD_ATTRS }}>
        {{ HEAD }}
        <script>
            if (document.monetization) {
              document.monetizationExtensionInstalled = true
            } else {
              document.monetization = document.createElement('div')
              document.monetization.state = 'stopped'
            }
          </script>
          <script src="https://cdn.coil.com/coil-oauth-wm.v7.beta.js" defer></script>
      </head>
      <body {{ BODY_ATTRS }}>
        {{ APP }}
      </body>
    </html>

Even then, you will get some flaky responses. I am unclear as to whether this is normal, or related to the compromises.

3. Your subscriber authenticates your rights to their monetisation account

At the end of this process you will have:

Set up TypeScript interfaces for requests and responses,

Set up all API request code,

Set up a proxy for queries to Coil,

Store the refresh_token as a cookie, and access_token and sub in the store,

[Optional] Request your subscriber's personal information.

Maybe go get some coffee. This is going to get very technical, very fast.

Set up your TypeScript interfaces

It is very easy to get lost amongst the keys and their requirements. TypeScript interfaces permit us to define what data we need to request, and what we expect in response. These are documented over several pages, but we'll pool them all in one, then use them throughout what follows. It will make things easier.

Create ./interfaces/coil.ts:

    /* eslint-disable camelcase */

    export interface ICoilUserResourceRequest {
      response_type: string
      scope: string
      client_id: string
      state: string
      redirect_uri: string
      prompt: string
    }

    export interface ICoilUserResourceResponse {
      code: string
      state: string
      scope: string
    }

    export interface ICoilUserTokenRequest {
      code: string
      grant_type: string
      redirect_uri: string
    }

    export interface ICoilUserTokenResponse {
      access_token: string
      expires_in: number
      id_token: string
      refresh_token: string
      scope: string
      token_type: string
    }

    export interface ICoilUserTokenRefreshRequest {
      refresh_token: string
      grant_type: string
      scope: string
    }

    export interface ICoilUserTokenRevokeRequest {
      token: string
    }

    export interface ICoilUserInfo {
      email?: string
      sub: string
    }

    export interface ICoilUserBTP {
      btpToken: string
    }

That should be fairly readable. Interfaces for request are followed by a counterparty response. We make the request, we receive the response. It should all validate.

Set up all API request code

We'll go through this step-by-step ... I'm using Axios to make the requests.

1. Generate and present the referral URI to your subscriber

GOTCHA: While Coil states that you can refer the subscriber to either of a signup or login page, the reality is only login works. Note this for the prompt key in the API.

In Nuxt.js, create ./api/coil.ts:

import axios from "axios"
import {
  ICoilUserResourceRequest,
  ICoilUserTokenRequest,
  ICoilUserTokenResponse,
  ICoilUserTokenRefreshRequest,
  ICoilUserTokenRevokeRequest,
  ICoilUserInfo,
  ICoilUserBTP,
} from "@/interfaces"

export const coil = {

    getUserResource(coilState: string): string {
        // https://help.coil.com/docs/dev/get-oauth-auth#request-parameters
        // NOTE: currently the 'signup' prompt doesn't work
        // https://www.valentinog.com/blog/url/
        const getResourceURL = new URL(`${process.env.coilUrl}/oauth/auth`)
        const data: ICoilUserResourceRequest = {
          response_type: "code",
          scope: "simple_wm openid",
          client_id: (process.env.coilID as unknown) as string,
          state: coilState,
          redirect_uri: `${process.env.baseUrl}/support-us`,
          prompt: "login",
        }
        for (const [key, value] of Object.entries(data)) {
          getResourceURL.searchParams.append(key, value)
        }
        return getResourceURL.href
    }

}

GOTCHA: coilState is a really important token you will use to ensure you can trust the response from Coil (i.e. no spoofing of your website by sending random scripts to your processing page). Effectively, you generate a random string, send that to Coil along with your request, then Coil sends it back. It is YOUR responsibility to validate the state you receive as being identical to the one you sent. I generate these as UUIDs:

In frontend create ./utilities/keys.ts:

function generateUUID(): string {
  // Reference: https://stackoverflow.com/a/2117523/709884
  // And: https://stackoverflow.com/a/61011303/295606
  return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (s) => {
    const c = Number.parseInt(s, 10)
    return (
      c ^
      (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (c / 4)))
    ).toString(16)
  })
}

You will call and use the generated URI in your redirect_uri page script.

In frontend, redirect processing page ./pages/support-us.vue:

this.coilRequestURI = coil.getUserResource(this.coilState)

And then use this to generate the "Sign in with Coil" button:

<a class="mt-9" :href="coilRequestURI"
  ><SvgIcon terms="w-56 h-10" icon="svgCoilWhite"
/></a>

Note: you defined which page you want Coil to return the subscriber's response as redirect_uri. It is this page where all the following processing will take place. Mine is ./pages/support-us.vue.

GOTCHA: You can't make requests from the frontend. You run straight into Cross-Origin Resource Sharing (CORS) errors where the requests and / or responses are blocked. You need to proxy your requests. This is especially painful if you were hoping for a Single-Page Application, or a static app.

Fortunately, I'm using FastAPI on the backend so it's relatively straightforward to set it up to proxy requests. We'll do that in the next section, so for here just note that the URIs for axios.post and axios.get are being requested from the backend, not Coil.

2. Receive and use response token to request subscriber authentication keys

The coil redirect will return to your response page, along with query terms in the path. It may look something like this:

response:

https://example.com/
?code=CU6LG36vKvVmUbF9QWFwj7F5zvY
&state=b5f1872f-9d32-5f31-819d-5a4daeab4ea9
&scope=simple_wm openid

First, parse this to extract the parameters and then send this for processing. I'm using the Nuxt Store to manage browser state.

In frontend, in redirect processing page ./pages/support-us.vue:

if (
  this.$route.query.code &&
  this.$route.query.state &&
  this.$route.query.scope
) {
  const payload: ICoilUserResourceResponse = {
    code: this.$route.query.code as string,
    state: this.$route.query.state as string,
    scope: this.$route.query.scope as string,
  }
  await this.getUserToken(payload)
}

The asyncronous await to getUserToken populates the store and triggers the cascade of authentication requests we need. In ./store/monetization/actions.ts:

async getUserToken({ commit, dispatch }, payload: ICoilUserResourceResponse) {
    if (getCoilState() !== payload.state) {
      await commit("setRequestError", true)
    } else {
      try {
        try {
          const response: AxiosResponse = await coil.getUserToken(payload.code)
          const data: ICoilUserTokenResponse = response.data
          await commit("setCoilToken", data.access_token)
          saveCoilRefresh(data.refresh_token)
        } catch (error) {
          await dispatch("checkCoilError", error)
        }
      } catch (error) {
        await dispatch("checkCoilError", error)
      }
    }
}

This requires a request to the coil API, and then we save the authentication token to the store, and the refresh token as a persistent cookie in the subscriber's browser.

This is the critical self-validation call to ensure that the response you receive is valid and from Coil:

if (getCoilState() !== payload.state) ...

Here is the next api call to Coil to pass back the token you received and exchange it for your subscriber's authentication and refresh tokens:

await coil.getUserToken(payload.code)

Back to ./api/coil.ts and pop this into the export:

async getUserToken(coilCode: string) {
    // https://help.coil.com/docs/dev/post-oauth-token/index.html#request-an-access-token-for-an-authenticated-user
    const data: ICoilUserTokenRequest = {
      code: coilCode,
      grant_type: "authorization_code",
      redirect_uri: `${process.env.baseUrl}/create`,
    }
    return await axios.post<ICoilUserTokenResponse>(
      `${process.env.apiUrl}/api/v1/coil/proxy/oauth/token`,
      data,
      requestHeaders()
    )
}

This is a post and you pass your app's authentication keys to Coil in the header:

requestHeaders()

That function is included in ./api/coil.ts:

function requestHeaders() {
  const token = btoa(`${process.env.coilID}:${process.env.coilSecret}`)
  return {
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${token}`,
    },
  }
}

GOTCHA: Note again that you're escaping your two keys, client_id and client_secret, as base64. Here using btoa. I don't know if this was just me, but I found that I had to do this 'twice'. I first converted client_secret to base64, then generated a new base64 string on the result btoa(client_id:client_secrect_base64).

Coil returns a response json object.

response:

{
  "access_token": "eyJhbGciOi...JSUzI1NfsQ",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUz...I1NiIsInR5",
  "refresh_token": "dzfKQUEFYXEZ2~WKq5t0atT36X~",
  "scope": "simple_wm", "openid",
  "token_type": "Bearer"
}

Store the `refresh_token` as a cookie, and `access_token` and `sub` in the `store`

This access_token authenticates you to request a BTP token which is what you need to begin streaming money. This token is only valid for an hour, and so I don't bother storing it in a persistent cookie, leaving it in the store. However, the refresh_token is valid indefinitely and so you need to take care with it.

ETHICS: You may be tempted to store this refresh_token in your database. DO NOT DO SO. It doesn't belong to you. It belongs to your subscriber. Should they wish to revoke your use of that token, it should never be a request to your database. They should have the power to simply clear their browser cookies.

Request your subscriber's personal information

Optional: Depending on how your app works, you may want your subscriber's personal information (user id and/or email). This is a separate request. It is not needed to authorise streaming.

In the store ./store/monetization/actions.ts:

async getUserInfo({ commit, dispatch, state }) {
    try {
      const response: AxiosResponse = await coil.getUserInfo(state.coilToken)
      const data: ICoilUserInfo = response.data
      await commit("setCoilSub", data.sub)
    } catch (error) {
      await dispatch("checkCoilError", error)
    }
}

Back in ./api/coil.ts:

async getUserInfo(accessToken: string) {
    return await axios.get<ICoilUserInfo>(
      `${process.env.apiUrl}/api/v1/coil/proxy/user/info`,
      requestUserHeaders(accessToken)
    )
}

GOTCHA: you are using both a new API endpoint for this request, as well as a new header. https://api.coil.com, and this header:

function requestUserHeaders(accessToken: string) {
  return {
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Bearer ${accessToken}`,
    },
  }
}

Where accessToken is the access_token you received from getUserToken.

In addition, your request to getUserInfo is a get request. That's a minor change here, but a big change on your proxy.

response:

{
  "sub": "22028a7c-b720-7a3e-4387-6c9845f6201b",
  "email": "alice@coil.com"
}

Set up a `backend` proxy for queries to Coil

As described earlier, all of the API calls in the Nuxt frontend are proxied to the FastAPI backend.

The way this works is, your frontend interacts with the subscriber and manages the monetization state. It then sends any queries it has direct to the server and immediately refers back any responses. It stores nothing and remembers nothing.

Python code follows, using HTTPX as the http client.

ETHICS: You'll see that, while your subscriber is anonymous (as are their payments), control over when to charge them and how to do so is not actually in their control. It's entirely in yours. That means you have to deliberately - from the beginning - make it easy to NOT ABUSE YOUR SUBSCRIBER. The only way you can do that effectively is if you resolve never to store any auth keys anywhere near your backend, but leave them entirely in your subscriber's browser. This is the reason we only proxy at the backend and not manage the entire process.

What follows is longer than it needs to be because of yet another gotcha.

GOTCHA: Coil's API has two inconsistencies. The first is that not all requests are POST. There is one GET. The second is that not all requests are to the same URI. It switches from https://coil.com to https://api.coil.com. You need to account for this in your proxy.

Create ./app/api/api_v1/endpoints/coil.py:

    from typing import Any
    from fastapi import APIRouter, HTTPException, Request, Response
    import httpx

    from app.core.config import settings


    router = APIRouter()
    # https://coil.com
    coil_uri = settings.COIL_URI
    # https://api.coil.com
    coil_api_uri = settings.COIL_API_URI


    # FOR POST
    @router.post("/proxy/{path:path}")
    async def proxy_post_request(*, path: str, request: Request) -> Any:
        # https://www.starlette.io/requests/
        # https://www.python-httpx.org/quickstart/
        # https://github.com/tiangolo/fastapi/issues/1788#issuecomment-698698884
        # https://fastapi.tiangolo.com/tutorial/path-params/#__code_13
        try:
            URI = coil_uri
            if path.startswith("user/"):
                URI = coil_api_uri
            data = await request.json()
            headers = {
                "Content-Type": request.headers["Content-Type"],
                "Authorization": request.headers.get("Authorization"),
            }
            async with httpx.AsyncClient() as client:
                proxy = await client.post(f"{URI}/{path}", headers=headers, data=data)
            response = Response(content=proxy.content, status_code=proxy.status_code)
            return response
        except Exception as e:
            raise HTTPException(status_code=403, detail=str(e))

    #FOR GET
    @router.get("/proxy/{path:path}")
    async def proxy_get_request(*, path: str, request: Request) -> Any:
        try:
            URI = coil_uri
            if path.startswith("user/"):
                URI = coil_api_uri
            headers = {
                "Content-Type": request.headers.get("Content-Type", "application/x-www-form-urlencoded"),
                "Authorization": request.headers["Authorization"],
            }
            async with httpx.AsyncClient() as client:
                proxy = await client.get(f"{URI}/{path}", headers=headers)
            response = Response(content=proxy.content, status_code=proxy.status_code)
            return response
        except Exception as e:
            raise HTTPException(status_code=403, detail=str(e))

That's all you need on the server, but let me give you a little context and explanation.

@router.post("/proxy/{path:path}")

FastAPI uses types and Pydantic to annotate variables. What's going to happen here is that all the text after path is going to be treated as a path type and provided as a variable to the function. We then use httpx to make a new post to Coil. Note, though, how we have to account for the gotcha of shifting endpoints.

URI = coil_uri
if path.startswith("user/"):
    URI = coil_api_uri

Then we regenerate our headers, get any data from the request in json/dict format, and proxy using httpx:

data = await request.json()
async with httpx.AsyncClient() as client:
    proxy = await client.post(f"{URI}/{path}", headers=headers, data=data)

GOTCHA: Coil response codes are a little unclear. The only failure code is a 403 request failure. You do get some text to explain the error, and you can send that back to the app, but I found it often quite obscure. It wasn't always clear what I had done wrong, or what wasn't working.

4. Your subscriber authorises your right to monetize your content

At the end of this process you will have:

Authorise your rights to monetize a subscriber,

Initialise your web monetization stream, and specify a destination wallet,

Refresh streaming tokens as required,

Stop / Revoke streaming in response to your subscriber's wishes.

Authorise your rights to monetize a subscriber

A btpToken - which is a promise to fulfill a payment request, not payment in and of itself - is only valid for 30 minutes. There is no point in generating one until your subscriber actually expresses their intention to stream money to your wallet.

You'll need some sort of "start" / "stop" UX on your app, and the Web Monetization Foundation has a great set of docs that explain exactly this. You can review those after this section. First we use the subscriber's authentication token to request a BTP token.

In the frontend store ./store/monetization/actions.ts:

async getUserBTP({ commit, dispatch, state }) {
    try {
      const response: AxiosResponse = await coil.getUserBTP(state.coilToken)
      const data: ICoilUserBTP = response.data
      await commit("setBtpToken", data.btpToken)
    } catch (error) {
      await dispatch("checkCoilError", error)
    }
}

Back in frontend ./api/coil.ts:

async getUserBTP(accessToken: string) {
    return await axios.post<ICoilUserBTP>(
      `${process.env.apiUrl}/api/v1/coil/proxy/user/btp`,
      {},
      requestUserHeaders(accessToken)
    )
}

There's no point in storing the token outside of the store. It is valid for only 30 minutes from the time of issue, whether it is used or not.

GOTCHA: the request to get the btpToken is both in camel-case, and a post. It also has no data to send in post, so ensure you include an empty object: {}. It also uses https://api.coil.com. Both the request to get user info, and BTP token are the only requests to this root endpoint.

response:

{
  "btpToken": "eyJhbGciOiJCchQ8...SeOz98I2Sqyf1LrVM"
}

Now you have a btpToken, but possession of a token is not money. That still needs to happen in the next process.

Initialise your web monetization stream, and specify a destination wallet

We'll start with the gotcha.

GOTCHA: The challenge of websites is also the purpose of JavaScript web frameworks, like Node. To manage, and persist, state. The more you can persist between state changes (shifting between different web pages) the more a website can feel like a native application. A Progressive Web App is all about near native user-experience. Problem is, the current Coil OWM script does not seem to expect this. Their documentation expressly states "Add the following code to the <body> section of each page you are monetizing.":

<script>
    document.coilMonetizationPolyfill.init({ btpToken: 'USERS_TOKEN_HERE' })
</script>

Doing that in a Node app, though, will instantly crash your app during transitions since this is exactly the sort of state that Node will preserve. That means initialising the coilMonetizationPolyfill needs to look like this on every page:

if (
  process.client &&
  Object.prototype.hasOwnProperty.call(document, "coilMonetizationPolyfill")
)
  try {
    document.coilMonetizationPolyfill.init({ btpToken: this.btpToken })
  } catch (error) {}

In words: check that your script will execute only client-side, and that the coilMonetizationPolyfill has been initialised, and then try/catch to initialise it with the btpToken.

I created a single "start" / "stop" component to listen to subscriber instructions.

In frontend ./components/monetization/MenuToggle.vue:

public setMonetizationTag() {
    // https://github.com/Techgethr/webmonvuejs/blob/main/index.js
    // https://webmonetization.org/docs/start-stop/
    const monetizationTag = document.querySelector('meta[name="monetization"]')
    if (!monetizationTag && this.coilPointer) {
      const meta = document.createElement("meta")
      meta.name = "monetization"
      meta.content = this.coilPointer
      document.getElementsByTagName("head")[0].appendChild(meta)
    }
    if (monetizationTag && !this.coilPointer) {
      monetizationTag.remove()
    }
}

ETHICS: The way that the OWM script "listens" to whether or not a valid BTP token should be used to stream payments is whether or not there is a metatag pointing to a wallet. You end streaming payments by removing the pointer. Everyone, from your subscriber, to Coil, to the Web Monetization Foundation and Grant for the Web are relying on you to honour your subscriber's intentions and expressed instructions.

When your subscriber tells you to stream, you add the wallet pointer:

if (!monetizationTag && this.coilPointer) {
  const meta = document.createElement("meta")
  meta.name = "monetization"
  meta.content = this.coilPointer
  document.getElementsByTagName("head")[0].appendChild(meta)
}

And when they tell you to stop, you remove it:

if (monetizationTag && !this.coilPointer) {
  monetizationTag.remove()
}

That's the entirety of your subscriber's protection from abuse of their trust in you. That you MUST honour their instructions and delete the wallet pointer. Please - and I know I'm whispering in a thunderstorm - please don't abuse this.

Refresh streaming tokens as required

"Start" and "Stop" is equivalent to a call to check the validity of a token, and refresh them as required.

In the same frontend component ./components/monetization/MenuToggle.vue

public async toggleMonetizationStreaming() {
    if (!this.isStreaming) await this.startMonetizationStream()
    else await this.stopMonetizationStream()
    this.setMonetizationTag()
}

This is in response to the subscriber toggling a button in the menu bar of the app.

It is your responsibility to check that a BTP token is still valid. A JWT token intrinsically contains the time it was created, so you can easily check.

In frontend ./utilities/keys.ts:

function getTimeInSeconds(): number {
  // https://stackoverflow.com/a/3830279/295606
  return Math.floor(new Date().getTime() / 1000)
}

function tokenExpired(token: string) {
  // https://stackoverflow.com/a/60758392/295606
  const expiry = JSON.parse(atob(token.split(".")[1])).exp
  return getTimeInSeconds() >= expiry
}

And then on to the frontend store, where we manage monetization state ./store/monetization/actions.ts:

  async startMonetizationStream({ commit, dispatch, state }) {
    await dispatch("refreshUserBTP")
    if (!state.requestError) {
      await commit("setIsStreaming", true)
      await commit("setCoilPointer", process.env.coilPointer as string)
      await commit(
        "main/addNotification",
        {
          content: "You have started web monetization.",
          color: "success",
        },
        { root: true }
      )
    }
  }

Refreshing the BTP token triggers a cascade of requests. I felt there was no point in worrying about the difference between an authentication_token valid for 60 minutes, and a btpToken valid for 30. Just refresh both of them.

In the frontend ./store/monetization/actions.ts:

async refreshUserBTP({ commit, dispatch, state }) {
    if (getCoilRefresh()) {
      try {
        const response: AxiosResponse = await coil.getUserRefresh(
          getCoilRefresh() as string
        )
        const data: ICoilUserTokenResponse = response.data
        // https://stackoverflow.com/a/32108184/295606
        if (
          data &&
          Object.keys(data).length !== 0 &&
          data.constructor === Object
        ) {
          await commit("setCoilToken", data.access_token)
          saveCoilRefresh(data.refresh_token)
          if (!state.requestError) {
            await dispatch("getUserBTP")
            await commit("setRequestError", false)
          }
        } else {
          await commit("setRequestError", true)
        }
      } catch (error) {
        await dispatch("checkCoilError", error)
      }
    } else {
      await commit("setRequestError", true)
      await commit(
        "main/addNotification",
        {
          content: "Error authorising web monetization.",
          color: "error",
        },
        { root: true }
      )
    }
}

You'll note that there are profoundly numerous points in the process where things can go wrong and try / catch is triggered.

With the frontend api request in ./api/coil.ts:

async getUserRefresh(refreshToken: string) {
    const data: ICoilUserTokenRefreshRequest = {
      refresh_token: refreshToken,
      grant_type: "refresh_token",
      scope: "simple_wm openid",
    }
    return await axios.post<ICoilUserTokenResponse>(
      `${process.env.apiUrl}/api/v1/coil/proxy/oauth/token`,
      data,
      requestHeaders()
    )
}

With that you can get your BTP token, as described above.

Stop / Revoke streaming in response to your subscriber's wishes

Technically, all that's required to stop the process is to remove the wallet pointer in the metatag.

In the frontend ./store/monetization/actions.ts:

async stopMonetizationStream({ commit }) {
    await commit("setIsStreaming", false)
    await commit("setCoilPointer", "")
    await commit(
      "main/addNotification",
      {
        content: "You have stopped web monetization.",
        color: "success",
      },
      { root: true }
    )
}

Cascading back up the code, you call this.setMonetizationTag() which removes the metatag pointer.

From the frontend component ./components/monetization/MenuToggle.vue

if (monetizationTag && !this.coilPointer) {
  monetizationTag.remove()
}

Revoking is slightly more convoluted. If a subscriber revokes, you need their authentication_token to perform the action. However, their token may no longer be valid, so you may need to first refresh their token and only then revoke your access to their keys.

In the frontend ./store/monetization/actions.ts:

async revokeMonetization({ commit, dispatch, state }) {
    await dispatch("stopMonetizationStream")
    if (state.coilToken) {
      await coil.revokeUserResource(state.coilToken)
      await commit("setCoilToken", "")
    } else if (getCoilRefresh()) {
      // Counterintuitively, we need a new user_token to request the revoke
      try {
        const response: AxiosResponse = await coil.getUserRefresh(
          getCoilRefresh() as string
        )
        const data: ICoilUserTokenResponse = response.data
        if (
          data &&
          Object.keys(data).length !== 0 &&
          data.constructor === Object
        )
          await coil.revokeUserResource(data.access_token)
      } catch (error) {
        await dispatch("checkCoilError", error)
      }
    }
    if (getCoilRefresh()) removeCoilRefresh()
    await commit(
      "main/addNotification",
      {
        content: "You have successfully revoked web monetization.",
        color: "success",
      },
      { root: true }
    )
}

With the frontend api request in ./api/coil.ts:

async revokeUserResource(token: string) {
    const data: ICoilUserTokenRevokeRequest = {
      token,
    }
    return await axios.post(
      `${process.env.apiUrl}/api/v1/coil/proxy/oauth/token/revocation`,
      data,
      requestHeaders()
    )
}

There is no response to a revoke request. However, remember we adopted an ethical design approach. If our subscriber has deliberately cleared their cookies, we no longer have access to their refresh_token anyway, and so no longer have access to their account.

And that's it (so far). There's more we can do ... split payments (proportionally specifying which wallet pointer is monetized), opening up sections of your app to streaming subscribers, etc. All of that requires a rock-solid payment process, and I hope this guide helps save you at least some time and frustration in achieving that.

Please let me know in the comments what you think, what I missed, and what can be fixed / improved.

References

For both this guide, and for those of you wishing to go further and add things like scheduled token refresh, proportional payments, etc.

Qwyre.com - What does a minimum lovable product even look like?

Gavin Chait — Tue, 10 Aug 2021 16:20:12 +0000

One of the management-speak fads of the last decade has been the minimum viable product which, instinctively, we probably all know is wrong. It leaves us with scaffolding and dodgy wiring. Made things that are difficult to use, fail easily, and add to the noise and clutter of the world.

They can be important early steps, but they're difficult to "love". And, if what we want is people to switch to wanting to use what we make, we need to offer at least a modicum of enjoyment to these fledgling efforts.

This approach is the minimum lovable product. Unlike MVP, MLP doesn't seem to have an established parent, but the earliest visual representation of this I can find is from Jussi Pasanen:

// Detect dark theme var iframe = document.getElementById('tweet-515301088660959233-135'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=515301088660959233&theme=dark" }

Henrik Kniberg, writing in 2016, presented a more visual way or representing this:

Problem is, this implies you know what all of these intermediate things are when all you've got is this wheel you invented. Except ... none of us invented a wheel in a world of pedestrians. We're iterating on what exists.

In the case of Qwyre, that means there are already many ways to convert a document to an epub, and multiple ways to publish them. I know what my iteration looks like at the end, but I want an interim release, and that release needs to be useful.

Useful to me so I can get feedback and test how webmonetization works in production, but definitely useful to people so that they want to give me that feedback in the first place.

Originally, I thought I'd go as far as releasing an epub converter and call that interim.

The more I sat with that, though, the less enjoyable that became. The process of conversion is easy-enough, and the design - while interim - is inoffensive. I'm a professional writer, and this is also a tool I'd like to use.

But ... my workflow, using my own app, was:

Generate the epub,
Download it,
Import it into Calibre,
Check that it looks ok.

That's a lot of effort, and distinctly displeasing. I can't ask anyone else to struggle that way.

I decided that the interim app needs to have a functioning ereader. But you can't have a MVP ereader in this here 2021. It has to be an ereader. Which led me to the rabbit-hole of Epub.js, still the only mostly-functioning open-source browser-based ereader library:

futurepress / epub.js

Enhanced eBooks in the browser.

There is documentation, but no actual developer manual, and definitely no tutorials. The API appears to have changed without notice, so what works in other packages doesn't work anymore. It's a bit tedious. I'm also a little nervous as to how large it is, but I'll see how that goes once I get to the build point.

A large-scale digression over the last five weeks means this is possible:

The app is a Progressive Web App, and I'm using IndexedDB to store data in the browser to make the user-experience truly offline. You can store all your epubs in the app, just like a real reader, and it is fully mobile responsive, meaning swipes and taps work as well.

My workflow now is:

Upload and convert a doc to epub,
Read my epub...
Get lost importing and reading other ebooks.

Which is the way it's supposed to be.

The app itself works fine for release, but I still want to get basic webmonetization implemented, and then it should be ready to deploy for interim release. I've just picked up another project, so I'm going to be delayed for a few weeks, but hopefully by early September.

One thing I'd like to know, though (for those who read this far) ... what is your favourite ereader app (not device), and what features makes it special for you?

Qwyre.com - a framework for ethics and technical development in fiction publishing

Gavin Chait — Wed, 30 Jun 2021 17:53:26 +0000

Two months after my dad died, I was sitting on a beach in the Philippines writing my first novel. My dad's passing was expected. My writing trip long-planned. It's the sequence that wasn't the one I had hoped.

I wrote 2,000 words a day for a month, and, when it was done, the orbital prison of Tartarus and the remote Nigerian village of Ewuru were real.

Lament for the Fallen

Isolated and with his orbital city hiding in the rubble of a devastating war, Samara falls 35,000km to escape from the space-based prison of Tartarus, smashing into the jungle near an isolated Nigerian village. Struggling to heal, and hunted by a brutal warlord in a ruthless land, Samara searches for a way home to the woman he loves.

I never expected an agent or publishing contract, didn't want to rely on Amazon, and so I rolled my own. Within a few months, my long-term software roadmap became moot when Penguin Random House picked up LAMENT for publication. The world of creative self-publishing stops at the border of formal publication.

turukawa / whyqd

Whyqd is an extensible object-based wiki bringing revision control, content presentation, forking and embedding to any type of digital object.

A publishing house must have a list of titles, each within a set of genres conforming to the topics in the average bookshop. They make their money off their handful of giants, and do little to promote or develop the careers of their mid-list writers. You are expected to promote your own work, but you can't sell your own work. Twitter ok. Experimental self-publishing definitely not.

The challenge with lists and genres is that success is a game of whack-a-mole. Success leads to copycats, leads to perpetuation of specific norms. For African writers, this has meant we need to conform to an industry notion satirised by Binyavanga Wainaina in his frustrated guide on How to Write About Africa:

Never have a picture of a well-adjusted African on the cover of your book, or in it, unless that African has won the Nobel Prize. An AK-47, prominent ribs, naked breasts: use these. If you must include an African, make sure you get one in Masai or Zulu or Dogon dress.

A continent of 54 countries, countless ethnicities, and over a billion people reduced to a cartoon cameo in the mid-list.

A framework for African collaborative publishing

Umumtu ngumuntu ngabangtu

The African philosophy of Ubuntu can be summarised as "I am because we are." As I writer, I am both reader and writer because there are other writers. There is no line between writer and reader just as there is no line between genres, stories and influences.

Qwyre starts with the following simple principles:

All Qwyre users are creators,
A creator can perform any task of:
- Reading,
- Writing,
- Editing,
- Curating.
The path to publication requires appointing an editor and letting them decide when a creative work is ready,
Editors and curators are first-class citizens in the creative process and should be paid,
An forum of peers is there to resolve disputes,
Popularity can be gamed and is no guide to what a reader may enjoy,
All writers should have an equal shot at being read.

In practice, this implies moderated publication. There is no gatekeeping. We do not assign an editor and decide who gets published. All we require is that a writer recruit and appoint an editor, and that their editor gets to decide when their work is ready for publication. This will require an appeals process, and so we need an editors forum.

This leads to the following structured components to support a Qwyre workflow:

EPUB generator: convert a .docx file to a standards-compliant .epub,
Editor recruitment: manage the recruitment and contractual agreement between a writer and editor,
eReader: an online standards-compliant EPUB reader,
Web monetisation: books can be read by streaming and, once paid for via monetisation, can be downloaded as an epub,
Editor's forum: a formal review process to permit dispute resolution between writers and their editors,
Curation: create lists of works which can be shared and promoted,
Search and discovery: a neutral, automated method to categorise and assess creative works to support reader discovery.

At this time, given the diverse needs of writers and their preferred ways of working, Qwyre will not offer any online editing or writing support. These are to take place offsite.

Where possible, components will be released as free-standing apps as they are developed. The most immediately obvious of these are the EPUB generator, and the ereader app.

Nuxt.js and FastAPI as our technical stacks

Qwyre will be a progressive web app (PWA) with offline support for the reader's library of ebooks. Books can be bought as epubs, or streamed via web monetisation. What a reader "buys" via web monetisation, they own. Once they have streamed an entire book, they are able to download an epub version of the work.

I have developed on Django for years and enjoyed it, and its documentation. Recently, however, I've wanted to try something new and more in line with my current standards-based approach to data curation. Python's support for types has evolved, and the most modern and mature framework for working with Pydantic is FastAPI which comes with a Docker base project with PostreSQL and Vue.js. I didn't want to faff too much with Vue, and set out to produce a version for Nuxt.js (which is to Vue what Next is to React) as well as replacing Vuetify with Tailwind for the user interface design.

whythawk / nuxt-for-fastapi

Nuxt.js frontend drop-in replacement for Vue.js FastAPI base project generator.

This provides a solid starting point for further development.

Current development: Chapisha and EPUB Generator PWA

Chapisha provides an intuitive method for converting a well-formatted Microsoft Word .docx file into a standards-compliant EPUB3 ebook. I developed the standalone Python package to support a Nuxt.js progressive web application.

whythawk / chapisha

Python-based docx to standards-compliant epub3 conversion

The core functionality for the EPUB convertor is almost complete.

Next up is to work with Coil's web monetisation API and test streaming payments to support EPUB conversion. The specific mechanism is that:

A creator provides all the content and metadata required to generate an EPUB in the PWA,
Data only transfer from the creator to the Qwyre server during the generation process,
During generation, they can stream payments to support the app,
Streaming is monitored directly using websockets giving the creator feedback on the generation process, and costs,
On completion, all creator data is deleted from the server and returned to the creator.

I'm hoping to complete this in mid-July and deploy a test server with the EPUB generator for public testing and use by the end of July 2021. In my next update, I'll hopefully have a link for you to go test what I built so far.

I'm keen on feedback and discussion, so please get in contact and let me know your thoughts or concerns.

The Interledger Community 🌱: Qwyre

'Empathy' - new African speculative fiction by Cheryl Ntumy on Qwyre.com

Qwyre.com - What we learned, and our ethical foundations and plans for future development [Grant Report #2]

Makers are not speculators. Risk is not theirs to take.

Making monopolised proprietary lock-in impossible

Patience and the new

Qwyre launches its first web-monetized African speculative fiction short-story competition

Publishing your work on Qwyre.com

Prepare your work for publication

A call to readers and writers

Qwyre.com — Converting a digital work into a monetized stream [Grant Report #1]

Converting digital objects into digital streams

Progress on objectives

Preparation of a work for publication

Development and monetization receipts ...

What's next?

What community support would benefit your project?

Qwyre.com - A guide for integrating Coil & Web Monetization APIs for creatives doing the job once

Notes to the guide

Approach

Development stack

whythawk / full-stack-fastapi-postgresql

Full stack, modern web application generator. Using FastAPI, PostgreSQL as database, Nuxt3, Docker, automatic HTTPS and more.

Gotchas

Web Monetization is about authentication and authorisation

1. Authenticate your app with Coil

2. Embed the OAuth Web Monetization (OWM) script in your app

3. Your subscriber authenticates your rights to their monetisation account

Set up your TypeScript interfaces

Set up all API request code

Store the refresh_token as a cookie, and access_token and sub in the store

Request your subscriber's personal information

Set up a backend proxy for queries to Coil

4. Your subscriber authorises your right to monetize your content

Authorise your rights to monetize a subscriber

Initialise your web monetization stream, and specify a destination wallet

Refresh streaming tokens as required

Stop / Revoke streaming in response to your subscriber's wishes

References

Qwyre.com - What does a minimum lovable product even look like?

futurepress / epub.js

Enhanced eBooks in the browser.

Qwyre.com - a framework for ethics and technical development in fiction publishing

turukawa / whyqd

Whyqd is an extensible object-based wiki bringing revision control, content presentation, forking and embedding to any type of digital object.

A framework for African collaborative publishing

Nuxt.js and FastAPI as our technical stacks

whythawk / nuxt-for-fastapi

Nuxt.js frontend drop-in replacement for Vue.js FastAPI base project generator.

Current development: Chapisha and EPUB Generator PWA

whythawk / chapisha

Python-based docx to standards-compliant epub3 conversion

Web Monetization is about `authentication` and `authorisation`

Store the `refresh_token` as a cookie, and `access_token` and `sub` in the `store`

Set up a `backend` proxy for queries to Coil