flowrakis GNU Taler Payment and Donation Module for nuxt

A Payment Module for Nuxt/Vue.js

Module to add direct GNU Taler support in Nuxt

The GNU Taler is a privacy-preserving digital payment system which could be dubbed as the digital online equivalent to analogue offline cash. It allows for anonymous payments and is very fast and easy on the resources. It it something quite different than Crypto, because it is not itself a Currency, but a mathematically secured protocol to transfer amounts of potentially any currency.

As you might know Nuxt is a widely used JavaScript library for building web interfaces based on the lightweight Vue.js framework. This project will create a dedicated GNU Taler module for Nuxt, allowing developers the same convenience when supporting a privacy-friendly option they would have using Nuxt modules for proprietary services like Stripe and PayPal. It includes Vue.js components for donation and order payment, documentation and examples such as a file-based webshop.

Just in case you wonder. flowrakis is primarily a namespace that comes with a very specific coding philosophy. It literally means The Little Flow and by prefixing it to almost any member and variable it provides concise terminology and hence very solid semantic safety.

This project is kindly supported by NGI Taler .

Requirements

For using Talers

Primarily you need a Taler Wallet in your Browser, which you can install from https://www.taler.net/de/wallet.html here, if you don't have one.

If you don't have any $KUDOS or $TESTKUDOS Currency in your wallet, you can create a taler bank account at https://bank.demo.taler.net/ or https://bank.test.taler.net/ and directly charge up your wallet from there. (Where, if they differ, 'demo' marks the ore stable instance, and 'test' the more cutting edge one. -

If you want to play around beyond the included taler Merchant sandbox with your own taler Merchant Backend Instance, where you can view, process and refund orders made from this nuxt module project, you can create one at https://backend.demo.taler.net/ or https://backend.test.taler.net/

For Development

You need Node.js to run it and git to clone it.
With Node.js comes npm - https://docs.npmjs.com/about-npm/ - needed to manage packages and execute project scripts. But there are others, alternatives like pnpm - https://pnpm.io/installation/ -.
And naturally we recommend VSCodium - https://vscodium.com/ - for coding and debugging.

Quick Starts

Quick Start for Consuming Developers

Install the package

$ npm install --save flowrakis-taler_nuxt-module # or better use pnpm.

Add the module to your `/nuxt.config<js/`>

export default defineNuxtConfig({
, modules:[ 'flowrakis-taler_nuxt-module' ]})

And you are ready to use the module with the sandbox demo account as easy like this in your /app.vue/ for instance. Just provide a flowrakisOrderType in the body of your api request.

const flowrakisApi = '/api/flowrakis/order'
/** @type {flowrakisOrderType} */
const flowrakisOrder = {
talerMerchantId:'sandbox'
, flowrakisAmount:1.00
, flowrakisCurrency:'$KUDOS'
, flowrakisDescription:'unit of healthy food' }
const myOrder = await $fetch(
flowrakisApi
,{ method:'post'
, body:flowrakisOrder })

Once this works add your own taler Bank Merchant instances and enter the acquired credential them in a file above your project older called ../flowrakisSecrets.json. This would look something like this:

{"talerMerchantBackendConnectionArray": [ {
"talerMerchantId": "merchant-1ab2c3d4"
, "talerMerchantToken": "1a2b3c4d5e6f"
, "talerMerchantFullName": "your-name"
, "flowrakisCurrency": "$KUDOS"
, "talerMerchantInstanceHostUrl": "https://backend.demo.taler.net"}]}

As long as they have a unique talerMerchantId the flowrakis-taler_nuxt-module will automatically select the right connection as provided in the flowrakisOrder.

Quick Start for Evaluating or Contributing Developers

Clone the repository and run the playground with `npm run dev:quickstart` and open http://localhost:3000

git clone https://open.code.flowrakis.eu/flowrakis/flowrakis-taler_nuxt-module.git
cd flowrakis-taler_nuxt-module
npm run dev:quickstart

In the playground you can make an arbitrary order and pay with GNU Taler $KUDOS or $TESTKUDOS from your in browser's taler Wallet.

Basic Architecture

The module takes a dual REST API approach by providing an abstracting and general layer with comfortable derivative defaults, and another that is as truthful to the gnu taler merchant backend api. They are separated by namespaces, the first one using the flowrakis namespace, the second one a taler namespace, which we try to keep unpolluted from the flowrakis-namespace. If you call for instance /api/flowrakis/ to post a new order this will fill in all derivable defaults, like the merchant backend url from the talerMerchantId, and then relays the enriched request to localhost:3000/api/taler/merchant/private/orders/. But you can also use the latter one directly, if you want to stay close to that api.

Docs and Types

This project does the typing and the api documentation with jsdoc in such a manner that it can be typechecked in vscodium and the likes as well as from the shell.

API Documentation

You find the jsdoc generated documentation under https://open.code.flowrakis.eu/flowrakis/flowrakis-taler_nuxt-module/src/branch/master/docs/jsdoc/index.html where the types are also documented.

Type Safety Checking

Run

npm run types:check

to do a full check or use the VSCodium problems panel to solve type issues one by one with realtime feedback.

Taler Ecosystem

Taler Merchant

Head over to https://backend.demo.taler.net to login as user sandbox with password sandbox or to create/use your own taler Merchant instance.

Here you can view orders, refund them, send payment links, and quite a bit more, actually.