A free and fully open-sourced ecosystem of widgets, a front-end library, and back-end services — to make addition of \"logins\" and \"in-app-purchases\" (IAP) to your app as banal as possible.
\r\n\r\n# pay2my.app widgets\r\n\r\nCustomizable web-components enabling login and in-app purchases (IAP, paid up-sells) for any Web application to be as simple as possible.\r\n\r\nThe web-components are backed by the [legers.js library](https://www.npmjs.com/package/ledgers.js) in the browser and [renumeration APIs](https://overhide.io/2020/09/06/remuneration-api.html) to allow IAP in US dollars, ethers, and bitcoins (easily extensible to other cryptos).\r\n\r\nEverything is open-source.\r\n\r\nThe authentication and authorization mechanism used herein is the [Ledger-Based Authorizations](https://overhide.io/2020/10/11/what.html): crypto authorization concepts abstracted out for use with US dollars and any ledger based currency.\r\n\r\n\r\n\r\n> 👉 jump to the [demos](#demos)\r\n>\r\n> 👉 read the [tutorial](https://github.com/overhide/pay2my.app/blob/master/howto/intro/README.md)\r\n>\r\n> 👉 read the *remote-storage* app [tutorial](https://github.com/overhide/remotestorage-tutorial)\r\n>\r\n> 👉 reach out on [r/overhide](https://www.reddit.com/r/overhide/).\r\n\r\n\r\n\r\nIt's simple to add IAPs to your Web application — check out the \"simplest\" [demo](https://overhide.github.io/pay2my.app/demo-front-end/simplest.html) — it's essentially:\r\n\r\n```\r\n\r\n\r\n ...\r\n\r\n \r\n\r\n \r\n\r\n \r\n \r\n\r\n \r\n \r\n \r\n ...\r\n \r\n\r\n```\r\n\r\n\r\n\r\nThe above three web-components in an HTML page are all that's needed for the simplest authentication and authorization scenarios — allowing you to get paid ($2 in the above sample). The components use the [legers.js library](https://www.npmjs.com/package/ledgers.js) library and [renumeration APIs](https://overhide.io/2020/09/06/remuneration-api.html) to provide all functionality.\r\n\r\nNow, of course, the simplest example above is limited, it doesn't use a back-end and all code sits fully decompilable in the browser. It's useful for some scenarios, but for other scenarios you will want to [re-check authorizations in your back-end code and have feature-flows run through a back-end](https://overhide.io//2019/03/27/authorizations-and-exposed-source-code.html).\r\n\r\nMost demos in this repo have business flows incorporating one of two simple back-ends:\r\n\r\n- an [overhide.io hosted](https://overhide.io#baas) back-end\r\n- the [/demo-back-end](/demo-back-end) node.js application — that also runs in [Azure functions](https://azure.microsoft.com/en-us/services/functions/)\r\n\r\nYou can use the [overhide.io hosted](https://overhide.io#baas) back-end to authorize IAP data via the help of [lucchetto.js](https://www.npmjs.com/package/lucchetto/v/latest) or simply base your own back-end off of [/demo-back-end](/demo-back-end) it's very little code.\r\n\r\n\r\n\r\nThe below infographic conveys at-a-glance what you get with these widgets:\r\n\r\n
\r\nThe top-left shows a sample Web app with a nav-bar housing the [pay2myapp-status](#pay2myapp-status-) component. It also shows three purchase buttons. Clicking any of these will open up the [pay2myapp-login](#pay2myapp-login-) component which serves as our \"login widget\".\r\n\r\nWhen a user wants to authorize for a feature; different UI experiences will present themselves depending on whether the feature is free, the user wants to pay in dollars, or the user wants to pay using a wallet, e.g., above, see:\r\n\r\n- anti-bot authentication\r\n- purchase for dollars\r\n- puchase with crypto wallet\r\n\r\nA logged in user can check their previous payments in new browser tabs —Â UI experiences vary by currency/wallet.\r\n\r\n\r\n\r\n> ## Framework Users -- React.js, Angular, Vue.js, ...\r\n>\r\n> These are standard Web components written using [FAST](https://www.fast.design/).\r\n>\r\n> They [can be incorporated into any framework](https://www.fast.design/docs/integrations/introduction).\r\n>\r\n> An example/demo of these components used in a React.js app is provided in its own repository: [pay2my.app React.js Demo app](https://github.com/overhide/pay2my.app-react-demo).\r\n\r\n\r\n\r\n## Quick Start\r\n\r\nTo use these widgets in your Web app follow the steps below (or read through the [tutorial](https://github.com/overhide/pay2my.app/blob/master/howto/intro/README.md)).\r\n\r\nDon't just read these steps, follow along copying/looking-at the [demos](#demos).\r\n\r\nThe first three steps are gathering metadata necessary to setup how you, the developer, get paid.\r\n\r\nThe remainder of the steps are actual code changes in your Web application.\r\n\r\n\r\n\r\n1. onboard onto the dollar-ledger to get your US-dollar-ledger address ([production](https://ledger.overhide.io/onboard) | [testnet](https://test.ledger.overhide.io/onboard))\r\n\r\n - optional, you don't need this if you just want to accept cryptos or don't want in-app purchases at all (just authentication)\r\n - but, keep in mind, it's too early to just accept cryptos — most people online won't have any just yet and it's prudent to give them the option to pay in dollars\r\n - you will create a new [Stripe](https://stripe.com) account or connect your existing [Stripe](https://stripe.com) account\r\n - you will provide the above address as the *overhideAddress* attribute in all your [pay2myapp-appsell](#pay2myapp-appsell-) components (the feature buttons)\r\n\r\n2. onboard onto Ethereum (optional, recommended)\r\n\r\n - use a wallet such as [MetaMask](https://metamask.io/) to generate your credentials\r\n - you will provide your Ethereum public address as the *ethereumAddress* attribute in all your [pay2myapp-appsell](#pay2myapp-appsell-) components\r\n\r\n3. onboard onto Bitcoin (optional)\r\n\r\n - use a wallet such as [Electrum](https://electrum.org/#home) to generate your credentials\r\n - you will provide your Bitcoin public address as the *bitcoinAddress* attribute in all your [pay2myapp-appsell](#pay2myapp-appsell-) components\r\n\r\n4. pull in the `pay2my.app.js` component into your app, see [CDN](#cdn).\r\n\r\n5. add an [pay2myapp-hub](#pay2myapp-hub-) component to your DOM or [initialize programatically](#setting-the-pay2myapp-hub-programatically)\r\n\r\n - assign an *id* attribute to the hub if other components will de-reference this hub via their *hubId* attribtues; otherwise, call the *setHub(..)* explicitly on each of those components from script\r\n - configure the *token* attribute or *apiKey* (see [Enabling with Token](#enabling-with-token))\r\n - specify the *isTest* attribute if this is a testnet application, otherwise leave it out\r\n\r\n6. add an [pay2myapp-login](#pay2myapp-login-) component to your DOM\r\n\r\n - configure the *id* of the [pay2myapp-hub](#pay2myapp-hub-) element via the *hubId*, or call this elements's *setHub(..)* setter to set the hub element programatically\r\n - list all the desired authentication/authorization methods for this application, the various *overhide..Enabled* attributes in [pay2myapp-login](#pay2myapp-login-)\r\n - *overhideSocialMicrosoftEnabled* if you want Microsoft social-login against the US dollar ledger — must onboard step [1] above and specify *overhideAddress* in your [pay2myapp-appsell](#pay2myapp-appsell-) elements\r\n - *overhideSocialGoogleEnabled* if you want Google social-login against the US dollar ledger — must onboard step [1] above and specify *overhideAddress* in your [pay2myapp-appsell](#pay2myapp-appsell-) elements\r\n - *overhideWeb3Enabled* if you want customers to manage their US dollar ledger credentials with their Ethereum wallet such as [MetaMask](https://metamask.io/) — must onboard step [1] above and specify *overhideAddress* in your [pay2myapp-appsell](#pay2myapp-appsell-) elements\r\n - *ethereumWeb3Enabled* if you want to allow payments in ethers for customers with their Ethereum wallet such as [MetaMask](https://metamask.io/) — must onboard step [2] above and specify *ethereumAddress* in your [pay2myapp-appsell](#pay2myapp-appsell-) elements\r\n - *bitcoinEnabled* if you want to allow payments in bitcoins for customers with their Bitcoin wallet such as [Electrum](https://electrum.org/#home) — must onboard step [3] above and specify *bitcoinAddress* in your [pay2myapp-appsell](#pay2myapp-appsell-) elements\r\n - *overhideSecretTokenEnabled* if you want user-managed secret-token access against the US dollar ledger — must onboard step [1] above and specify *overhideAddress* in your [pay2myapp-appsell](#pay2myapp-appsell-) elements\r\n\r\n7. add an [pay2myapp-appsell](#pay2myapp-appsell-) component as an explicit \"login\" button (non-feature) to your DOM\r\n\r\n 1. optional, as the feature buttons —Â when clicked — will login your users if they're not yet logged in\r\n 2. configure the *id* of the [pay2myapp-hub](#pay2myapp-hub-) element via the *hubId*, or call this elements's *setHub(..)* setter to set the hub element programatically\r\n 3. do not provide any [pay2myapp-appsell](#pay2myapp-appsell-) attributesexcept for the *hubId* (above) and the *loginMessage*\r\n\r\n8. add [pay2myapp-appsell](#pay2myapp-appsell-) components to your DOM for each feature\r\n\r\n 1. configure the *id* of the [pay2myapp-hub](#pay2myapp-hub-) element via the *hubId*, or call this elements's *setHub(..)* setter to set the hub element programatically\r\n 2. provide a unique *sku* attribute per button\r\n 3. provide the desired *priceDollars* attribute, or 0 if setting up a for-free feature\r\n 4. provide the *authorizedMessage* attribute to be displayed when user is already authorized and just needs to click on the feature to enable / use\r\n 5. provide the *unauthorizedTemplate* attribute to be displayed when the user is not yet authorized to use the feature (insufficient funds, not auth'ed)\r\n 6. provide the *overhideAddress* attribute if onboarded for US dollar payments in step [1] above\r\n 7. provide the *ethereumAddress* attribute if onboarded for ethers payments in step [2] above\r\n 8. provide the *bitcoinAddress* attribute if onboarded for bitcoin payments in step [3] above\r\n\r\n## Demos\r\n\r\nWe have several component demo files in [/demo-front-end](/demo-front-end):\r\n\r\n| **Demo Name** | **Link** | **Code** | **Type of Back-End** | **Notes** |\r\n| ------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |\r\n| basic | [demo](https://overhide.github.io/pay2my.app/demo-front-end/basic.html) | [code](/demo-front-end/basic.html) | [overhide.io hosted](https://overhide.io#baas) | the basic demo —Â *pay2myapp-status* in the nav-bar, a login button, 3 feature buttons. |\r\n| no back-end | [demo](https://overhide.github.io/pay2my.app/demo-front-end/no-back-end.html) | [code](/demo-front-end/no-back-end.html) | none | a no [back-end](#back-end) demo, everything just in-browser —Â same as basic otherwise |\r\n| custom buttons | [demo](https://overhide.github.io/pay2my.app/demo-front-end/custom.html) | [code](/demo-front-end/custom.html) | [./demo-back-end](./demo-back-end) as [Azure Function](https://azure.microsoft.com/en-us/services/functions/) | same as basic demo but the login button has different colors and the feature buttons are ice cream desserts —Â see [slots](#slots-2) section of the [pay2myapp-appsell](#pay2myapp-appsell-) component below |\r\n| javascript-hub | [demo](https://overhide.github.io/pay2my.app/demo-front-end/javascript-hub.html) | [code](/demo-front-end/javascript-hub.html) | [overhide.io hosted](https://overhide.io#baas) | same as basic demo but the *pay2myapp-hub* component is not in the DOM, it's wired in via script |\r\n| simplest | [demo](https://overhide.github.io/pay2my.app/demo-front-end/simplest.html) | [code](/demo-front-end/simplest.html) | none | bare bones single button demo —Â the simplest demo, no [back-end](#back-end) |\r\n| 
[pay2my.app React.js Demo app](https://github.com/overhide/pay2my.app-react-demo) | [demo](https://github.com/overhide/pay2my.app-react-demo) | [code](https://github.com/overhide/pay2my.app-react-demo) | [./demo-back-end](./demo-back-end) as [Azure Function](https://azure.microsoft.com/en-us/services/functions/) | React.js version of these demos. |\r\n\r\n\r\n\r\nMost demos show:\r\n\r\n- a nav-bar at the top with an [pay2myapp-status](#pay2myapp-status-) web-component flush to the right.\r\n- a login button (which is just an [pay2myapp-appsell](#pay2myapp-appsell-) component with a *loginMessage* attribute instead of a *sku*)\r\n- 3 feature buttons ([pay2myapp-appsell](#pay2myapp-appsell-) components):\r\n - free\r\n - $2 up-sell\r\n - $3 subscription for 30 minutes\r\n\r\nEverything is optional except for the non-visible [pay2myapp-hub](#pay2myapp-hub-) web-component that can be wired via DOM or JavaScript (see the [javascript-hub demo](/demo-front-end/javascript-hub.html) for JS wiring).\r\n\r\nYou could just have a single up-sell / in-app purchase button, no status, no explicit login, and it will allow all the functionality (see \"simplest\" [demo](https://overhide.github.io/pay2my.app/demo-front-end/simplest.html) ([code](/demo-front-end/simplest.html)).\r\n\r\n\r\n\r\nThe [/demo-front-end/no-back-end.html](/demo-front-end/no-back-end.html) shows the use of these widgets without any back-end — shows use of widgets with just an API key, the back-end setup can be ignored for this one. This is OK for some projects, but is less bad-actor proof. All other demos leverage a back-end.\r\n\r\n#### Back-End\r\n\r\nMost of the above demos run their feature-flows via one of two back-ends:\r\n\r\n- an [overhide.io hosted](https://overhide.io#baas) back-end\r\n- the [/demo-back-end](/demo-back-end) node.js application — that also runs in [Azure functions](https://azure.microsoft.com/en-us/services/functions/)\r\n\r\nRegardless of back-end choice, when a user clicks a feature, the back-end is interrogated to complete the feature flow. \r\n\r\nEither back-end verifies authentication and authorization as per credentials provided and monies paid on a ledger of choice.\r\n\r\n##### Notes on the [overhide.io hosted](https://overhide.io#baas) back-end\r\n\r\nThe demos that leverage the [overhide.io hosted](https://overhide.io#baas) back-end also leverage the [lucchetto.js](https://www.npmjs.com/package/lucchetto/v/latest) module. This module has a nice convenience `getSku(..)` function that connects the *pay2myapp-appsell-sku-clicked* event data to the back-ends.\r\n\r\nThe back-ends are:\r\n\r\n- [https://test.rs.overhide.io](https://test.rs.overhide.io/) for testnet / fake money / coding\r\n- [https://rs.overhide.io](https://rs.overhide.io/) for live / production deployment\r\n\r\nSee [lucchetto.js](https://www.npmjs.com/package/lucchetto/v/latest) for details on how to onboard in-app purchase SKUs for use with the *Lucchetto* back-ends.\r\n\r\n> âš Note that the [overhide.io hosted](https://overhide.io#baas) back-ends are [remote-storage](https://remotestorage.io) servers supporting *remote-storage* applications. But you absolutly do not have to be writing a *remote-storage* application to leverage them: as the here-in demos demonstrate.\r\n>\r\n> But if you are interested in writing a *remote-storage* application with in-app purchases, check out the [remote-storage tutorial](https://github.com/overhide/remotestorage-tutorial).\r\n\r\n##### Notes on the [/demo-back-end](/demo-back-end)\r\n\r\nThe [/demo-back-end](/demo-back-end) serves a couple purposes on behalf of our front-ends:\r\n\r\n- retrieves [an overhide token](https://token.overhide.io/swagger.html) for use with *overhide* APIs — browser front-end code calls this to get the token and provide to the [pay2myapp-hub](#pay2myapp-hub-) component.\r\n- retrieves the fees-schedule (not actually leveraged in demos for simplicity, but provided for completness)\r\n - usually you'll want a single source of truth for your feature fees schedule\r\n- runs the feature-flow business logic on the back-end when corresponding feature button clicked in the front-end (`/RunFeature` endpoints)\r\n - has a bunch of mandatory `query` parameters to authenticate and authorize\r\n - feature will not run if bad authentication or insufficient funds on ledger for feature (as per parameters): will result in \"Unauthorized by Ledger-Based AuthZ-\" response.\r\n - the back-end calls [overhide APIs](https://overhide.io/2020/09/06/remuneration-api.html) to check authorizations, and requires the following pieces of information from the front-end (the `/RunFeature` query parameters):\r\n - *sku* —Â the feature name / tag to derefernce fees schedule\r\n - *currency* —Â one of 'dollars', 'ethers', 'bitcoins'\r\n - *from* — ledger specific address of the customer (the 'from')\r\n - *message* — message signed to prove ownership of *address* (NOTE, this is base64 encoded)\r\n - *signature* — signature of *message* for *from*\r\n - *isTest* — whether testnet ledgers should be used for authorization\r\n\r\nThe endpoints for these are discussed in the [Local Development](#local-development) section below.\r\n\r\n\r\n\r\nThe [/demo-back-end](/demo-back-end) code runs both as stand-alone *node.js* as well as on [Azure Functions](https://azure.microsoft.com/en-us/services/functions/) (instructions below in [Local Development](#local-development) section). \r\n\r\nThe above demos that hit this back-end code, hit it as it's stood up at https://demo-back-end.azurewebsites.net/api on Azure; but, it's easy enough to stand-up locally and play around (again, see [Local Development](#local-development) below).\r\n\r\n## Distributable\r\n\r\n> **âš Why is it so big?** \r\n>\r\n> We depend on [web3.js](https://github.com/ethereum/web3.js/) which has bloat issues:\r\n>\r\n> https://github.com/ChainSafe/web3.js/issues/1178\r\n>\r\n> As soon as that gets resolved, this distro will be smaller.\r\n\r\nThe *pay2my.app* 'dist' folder contains the distributable artifact.\r\n\r\nYou'll likely want to [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) the library in your script code.\r\n\r\nWithin your front-end projects; using *npm* simply: `npm install pay2my.app --save-prod`.\r\n\r\n#### Enabling with Token\r\n\r\nAPIs abstracted by *pay2my.app* require a bearer-token. The `token` is passed in to the `` component (see the [pay2myapp-hub](#pay2myapp-hub-) component section for details).\r\n\r\nThe component either takes a `token=\"..\"` retrieved from a back-end (optional) or an `apiKey=\"..\"` provided statically —Â less bad-actor proof, but OK for some projects.\r\n\r\nRetrieve an API key from https://token.overhide.io/register.\r\n\r\nAfter that, a token can be retrieved with a `GET /token` call (see https://token.overhide.io/swagger.html).\r\n\r\nAll demos below show one or the other.\r\n\r\n## CDN\r\n\r\nYou can include *pay2my.app* via CDN:\r\n\r\n* `https://cdn.jsdelivr.net/npm/pay2my.app@latest/dist/pay2my.app.js`\r\n\r\nYou can see all the [/demo-front-end/*.html](/demo-front-end) demos load it this way:\r\n\r\n```\r\n\r\n```\r\n\r\nIn our demos we specifically load the latest version, e.g. version *1.4.11*: `https://cdn.jsdelivr.net/npm/pay2my.app@latest/dist/pay2my.app.js`\r\n\r\nThe widgets can then be used in your DOM and via your framework JavaScript.\r\n\r\n\r\n\r\nIn [npm](https://www.npmjs.com/) based app projects, include the components and TypeScript definitions with your `package.json`:\r\n\r\n```\r\n\"dependencies\": {\r\n ..\r\n \"pay2my.app\": \"1.4.11\",\r\n ..\r\n}\r\n```\r\n\r\n\r\n\r\n## Content-Security-Policy\r\n\r\nIf you're serving pages with these components from a server that sets the `Content-Security-Policy` header, you'll need the following adjustments to your CSP:\r\n\r\n```\r\nscript-src 'self' *.overhide.io *.stripe.com\r\nconnect-src *.overhide.io *.stripe.com\r\nstyle-src 'self' 'unsafe-inline'\r\ndefault-src 'self' *.stripe.com\r\nframe-src 'self' *.overhide.io overhide.github.io overhide.b2clogin.com *.stripe.com\r\nframe-ancestors 'self'\r\n```\r\n\r\n\r\n\r\n## Widget Reference\r\n\r\nBelow is a reference of the four web-components provided, their attributes, properties, events, and override [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) for customizing.\r\n\r\n### ``\r\n\r\nThe *pay2myapp-hub* comopnent is the main glue component of the whole subsystem. \r\n\r\nThere can be only one *pay2myapp-hub* shared by all the other components.\r\n\r\nEach other component must be provided with an *pay2myapp-hub* either via the DOM or programatically.\r\n\r\n##### Setting the *pay2myapp-hub* via DOM\r\n\r\nSimply set an ID on the *pay2myapp-hub* component and pass it into the other components as the `hubId` attribute:\r\n\r\n```\r\n \r\n\r\n\r\n```\r\n\r\nWith this setup, if we're providing our API key right in the client code, just set the *apiKey* attribute on the *pay2myapp-hub* element (a la [no-back-end](/demo-front-end/no-back-end.html) and [simplest](/demo-front-end/simplest.html) demos).\r\n\r\nThe [basic](/demo-front-end/basic.html) and [javascript-hub](/demo-front-end/javascript-hub.html) demos provide the *apiKey* to the [lucchetto.js](https://www.npmjs.com/package/lucchetto/v/latest) helper which provides it to the injected *hub*. \r\n\r\nThe [custom](/demo-front-end/custom.html) demo provides the *pay2myapp-hub* element with a *token* explicitly retrieved from our [/demo-back-end](/demo-back-end) — effectively moving the *apiKey* from sitting in the HTML code to sitting in the back-end:\r\n\r\n```\r\n\r\n```\r\n\r\n- the wiring above is in response to retrieving [a valid token](#enabling-with-token) from the back-end — the `fetch`\r\n- we set the *token* on the hub using `setAttribute('token',..)`\r\n- the `BACKEND_CONNECTION_STRING` points at our back-end server (see [Target a Back-End](#target-a-back-end) section)\r\n\r\n##### Setting the *pay2myapp-hub* Programatically\r\n\r\nWe can get an instance of the *pay2myapp-hub* Web component by instantiating right in JavaScript via `document.createElement('pay2myapp-hub')`.\r\n\r\nWe then provide it into each component using the `setHub(..)` setter via ES6 / TypeScript class.\r\n\r\nTake a look at the [javascript-hub demo code](/demo-front-end/javascript-hub.html) ([demo](https://overhide.github.io/pay2my.app/demo-front-end/javascript-hub.html)).\r\n\r\nHere, the components wired into the DOM do not have a `hubId=..` attribute specified. There is no `` component in the template. Everything is done in the `window.onload`:\r\n\r\n```\r\n\r\n\r\n```\r\n\r\n- note that [lucchetto.js](https://www.npmjs.com/package/lucchetto/v/latest) sets our hub *apiKey* on this *hub* instance, not shown for brevity\r\n- we optionally set the *isTest* attribute\r\n- since we're not wiring the *pay2myapp-hub* component into the DOM, we explicitly call `hub.init()`\r\n- the remaining `document.querySelector..` calls find all the other pay2my.app web-components to set the newly initialized hub against them via their `setHub(..)` method\r\n\r\n##### \r\n\r\n##### Attributes\r\n\r\n*isTest*\r\n\r\n- set on element to indicate that all transactions/checks should be done against testnets\r\n- leave out if production / live environment\r\n\r\n*noCache*\r\n\r\n- set on element to indicate login metadata should not be persisted in the browser-local session cache; to aide perserve data across browser refreshes\r\n- usually left out\r\n\r\n*apiKey*\r\n\r\n- set on element if not providing a token but providing the *apiKey*\r\n- we do this in the [no-back-end](/demo-front-end/no-back-end.html) and [simplest](/demo-front-end/simplest.html) demos only —Â demos where we do not leverage a back-end\r\n- this allows anyone to see your *apiKey*; in the future we might throttle/black-list basedon *apiKey* (we don't as of yet)\r\n\r\n*token*\r\n\r\n- set on element to provide a token retrieved via your own back-end\r\n- most demos do this, see code exaple in [section](#setting-the-pay2myapp-hub-via-dom) above\r\n- it's preferred—Â but not strictly necessary —Â to have this indirection in case we start throttling by *apiKey* in the future: this way your *apiKey* is not shared\r\n\r\n##### Properties / Methods\r\n\r\nSee *IPay2MyAppHub* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts).\r\n\r\n##### Slots\r\n\r\nN/A —Â this is an invisible element and not customizable via slots.\r\n\r\n##### Events\r\n\r\n*pay2myapp-hub-sku-authentication-changed*\r\n\r\n- see *IPay2MyAppSkuAuthenticationChangedEvent* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts)\r\n\r\n```\r\nexport interface IPay2MyAppSkuAuthenticationChangedEvent {\r\n message: string,\r\n signature: string,\r\n from: string,\r\n imparter: Imparter,\r\n isAuthenticated: boolean;\r\n}\r\n```\r\n\r\n- indicated a change in authentication status\r\n- imparter indicates which authenticated, or `Unknown` if not authenticated (`isAuthenticated === false`)\r\n- `isAuthenticated === false` event only sent on logout\r\n- `isAuthenticated === true` events sent on successful login\r\n\r\n*pay2myapp-hub-sku-authorization-changed*\r\n\r\n- see *IPay2MyAppSkuAuthorizationChangedEvent* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts)\r\n\r\n```\r\nexport interface IPay2MyAppSkuAuthorizationChangedEvent {\r\n sku: string,\r\n isAuthorized: boolean,\r\n asOf: string | null | undefined\r\n}\r\n```\r\n\r\n- indicated a change in authorization status\r\n- `isAuthorized === false` events may not be sent\r\n\r\n*pay2myapp-hub-pending-transaction*\r\n\r\n- see *IPay2MyAppPendingTransactionEvent* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts)\r\n\r\n```\r\nexport interface IPay2MyAppPendingTransactionEvent {\r\n isPending: boolean;\r\n currency: string | null;\r\n}\r\n```\r\n\r\n- fired when we have a pending transaction. We're waiting for a transaction to finish. \r\n- this should be useful for spinners on custom pay2myapp-appsell components.\r\n- see use in [demos](#demos) when showing the [VISA instructional helper](/dem=o-front-end/assets/visa.png)\r\n\r\n```\r\n// This event fires whenever we're asked to topup funds.\r\n// We're using it here to show the VISA instructional helper image.\r\nwindow.addEventListener('pay2myapp-hub-pending-transaction',(e) => { \r\n console.log(`pending-transaction :: ${JSON.stringify(e.detail, null, 2)}`);\r\n if (e.detail.currency == 'dollars') {\r\n document.querySelector(\"#visa\").style.opacity = e.detail.isPending ? \"1\" : \"0\";\r\n }\r\n}, false);\r\n```\r\n\r\n\r\n\r\n### ``\r\n\r\nThe login widget.\r\n\r\nThe login providers you want to make available to your users can be customized here.\r\n\r\nThis component must be in your DOM, the other components such as [pay2myapp-appsell](#pay2myapp-appsell-) and [pay2myapp-status](#pay2myapp-status-) will trigger this component to raise a modal showing login providers —Â when necessary.\r\n\r\nAll login providers configured here should have corresponding addresses configured on all your [pay2myapp-appsell](#pay2myapp-appsell-) buttons.\r\n\r\n##### Attributes\r\n\r\n*hubId*\r\n\r\n- connect to the one and only hub shared among all components in this eco-system\r\n- this is the actual element ID of the [pay2myapp-hub](#pay2myapp-hub-) in the document model\r\n- if the [pay2myapp-hub](#pay2myapp-hub-) is not in the DOM or doesn't have an ID, you'll need to use the `setHub(..)` method (see [setting the hub programatically](#setting-the-pay2myapp-hub-programatically)).\r\n\r\n*overhideSocialMicrosoftEnabled*\r\n\r\n- if set on the element, enables US dollar ledger login / IAPs via Microsoft account social-login\r\n\r\n\r\n\r\n- requires that your [pay2myapp-appsell](#pay2myapp-appsell-) components specify your *overhideAddress* attribute (you're onboarded onto the pay2myapp-ledger)\r\n\r\n*overhideSocialGoogleEnabled*\r\n\r\n- if set on the element, enables US dollar ledger login / IAPs via Google account social-login\r\n\r\n\r\n\r\n- requires that your [pay2myapp-appsell](#pay2myapp-appsell-) components specify your *overhideAddress* attribute (you're onboarded onto the pay2myapp-ledger)\r\n\r\n*ethereumWeb3Enabled*\r\n\r\n- if set on the element, enables Ethereum ledger login / IAPs via ethereum wallet such as [MetaMask](https://metamask.io/)\r\n\r\n\r\n\r\n- requires that your [pay2myapp-appsell](#pay2myapp-appsell-) components specify your *ethereumAddress* attribute (you're onboarded onto the pay2myapp-ledger)\r\n\r\n*bitcoinEnabled*\r\n\r\n- if set on the element, enables Bitcoin ledger login / IAPs via bitcoin signing\r\n\r\n\r\n\r\n- requires that your [pay2myapp-appsell](#pay2myapp-appsell-) components specify your *bitcoinAddress* attribute (you're onboarded onto Bitcoin)\r\n\r\n*overhideSecretTokenEnabled*\r\n\r\n- if set on the element, enables US dollar ledger login / IAPs via secret token\r\n\r\n\r\n\r\n- requires that your [pay2myapp-appsell](#pay2myapp-appsell-) components specify your *overhideAddress* attribute (you're onboarded onto the pay2myapp-ledger)\r\n\r\n##### Properties / Methods\r\n\r\nSee *IPay2MyAppLogin* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts).\r\n\r\n##### Slots\r\n\r\n*closeButton*\r\n\r\n- the slot representing the little close button on the login modal\r\n- can be hidden or re-styled\r\n\r\n\r\n\r\n*header*\r\n\r\n- allows creating a header at the top of the login modal —Â no header by default\r\n- see custom buttons [demo](https://overhide.github.io/pay2my.app/demo-front-end/custom.html) ([code](/demo-front-end/custom.html)) for example, e.g.\r\n\r\n```\r\n \r\n\t
\r\n\t \r\n\t
\r\n\t\t
Custom Login
\r\n\t\t
(logo + no Google or bitcoin)
\r\n\t
\r\n\t
\r\n \r\n```\r\n\r\n\r\n\r\n##### Events\r\n\r\n*pay2myapp-login-open*\r\n\r\n- emited on modal open\r\n\r\n*pay2myapp-login-close*\r\n\r\n- emited on modal close\r\n\r\n### ``\r\n\r\nThe main buttons that enable authorized features in your application.\r\n\r\nClicking on a feature button when not logged in causes login unless the *inhibitLogin* attribute is specified.\r\n\r\nClicking on a feature that isn't authorized triggers the authorization flow (in-app purchase).\r\n\r\nClicking on a feature that's authorized raises the *pay2myapp-appsell-sku-clicked* event in response to which the feature-flow can continue to your back-end and be re-verified (for authorizations).\r\n\r\nThese widgets are fully customizable through [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).\r\n\r\n##### Attributes\r\n\r\n*hubId*\r\n\r\n- connect to the one and only hub shared among all components in this eco-system\r\n- this is the actual element ID of the [pay2myapp-hub](#pay2myapp-hub-) in the document model\r\n- if the [pay2myapp-hub](#pay2myapp-hub-) is not in the DOM or doesn't have an ID, you'll need to use the `setHub(..)` method (see [setting the hub programatically](#setting-the-pay2myapp-hub-programatically)).\r\n\r\n*orientation*\r\n\r\n- the customization slots in this element are by default in a vertical orientation, top-to-bottom\r\n- set this to 'horizontal' if the slots are to be oriented left-to-right\r\n\r\n*sku*\r\n\r\n- a unique name for the feature being authorized using this button\r\n\r\n*priceDollars*\r\n\r\n- US dollars and cents as the cost of this feature\r\n- the amount is always specified in US dollars, the system converts to necessary ethers or bitcoins\r\n\r\n*loginMessage* \r\n\r\n- if this button is supposed to be an overall login button and never be used for a feature, specify this message\r\n- if this message is specified, do not specify any other attributes other than the *hubId*\r\n- this message is shown in the *authorized-button* and *unauthorized-button* slots\r\n\r\n*alwaysLogin*\r\n\r\n- if this button should always show the login modal when clicked\r\n- set to true when no means to logout is provided — enables user to always choose authorization method\r\n- likely shouldn't be set if a button with *loginMessage* is provided or an [pay2myapp-status](#pay2myapp-status-) component is used in the page — as those buttons allow re-login\r\n- useful for donation buttons when they're the sole button on the page\r\n\r\n*authorizedMessage*\r\n\r\n- the button label to show in the *authorized-button* slot when this feature is authorized\r\n\r\n*unauthorizedTemplate*\r\n\r\n- the button label to show in the *unauthorized-button* slot when this feature is not yet authorized\r\n- the `${topup}` placeholder can be used in the template to show the outstanding amount of US dollars — how much the user need to pay to authorize\r\n\r\n*inhibitLogin*\r\n\r\n- if provided on the element, do not allow the user to login using this button when clicked, and the user is not yet logged in\r\n- this is useful if you do not want users to login using the feature buttons, only an explicit *pay2myapp-appsell* button with a *loginMessage* attribute set\r\n\r\n*bitcoinAddress*\r\n\r\n- the bitcoin address into which paid bitcoins are deposited — and which is checked for sufficient monies paid to authorize\r\n- âš do not have too many distinct bitcoin addresses in your rendered route / page\r\n - usually it's recommended you have one per rendered route (e.g. hitting F5 will cause a single request)\r\n - all addresses are checked for topups and the APIs are rate-limited per IP\r\n - your users will start getting [429 - Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) if too many addresses are provided and they're all checked on refresh\r\n\r\n*ethereumAddress*\r\n\r\n- the ethereum address into which paid ethers are deposited — and which is checked for sufficient monies paid to authorize\r\n- âš do not have too many distinct ethereum addresses in your rendered route / page\r\n - usually it's recommended you have one per rendered route (e.g. hitting F5 will cause a single request)\r\n - all addresses are checked for topups and the APIs are rate-limited per IP\r\n - your users will start getting [429 - Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) if too many addresses are provided and they're all checked on refresh\r\n\r\n*overhideAddress*\r\n\r\n- the US dollars ledger address which shows receipts for deposited payments — and which is checked for sufficient monies paid to authorize\r\n- âš do not have too many distinct overhide addresses in your rendered route / page\r\n - usually it's recommended you have one per rendered route (e.g. hitting F5 will cause a single request)\r\n - all addresses are checked for topups and the APIs are rate-limited per IP\r\n - your users will start getting [429 - Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) if too many addresses are provided and they're all checked on refresh\r\n\r\n*withinMinutes*\r\n\r\n- specifies the number of minutes the feature should be authorized once sufficient *priceDollars* is paid\r\n- this is useful for subscription features\r\n- in our demos we usually have one button that expires after 30 minutes\r\n- leave out for indefinite — default\r\n\r\n##### Properties / Methods\r\n\r\nSee *IPay2MyAppAppsell* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts).\r\n\r\n##### Slots\r\n\r\nThese elements have three slots for authorized versions of each button and three slots for unauthorized versions of each button.\r\n\r\nThe authorized versions are shown when sufficient monies have been paid to authorize the feature.\r\n\r\nThe authorized slots are:\r\n\r\n- *authorized-header*\r\n- *authorized-button*\r\n- *authorized-footer*\r\n\r\nThe unauthorized slots are:\r\n\r\n- *unauthorized-header*\r\n- *unauthorized-button*\r\n- *unauthorized-footer*\r\n\r\nBy default nothing is rendered in the *-header* or the *-footer* slots, all rendering is done in the *-button* slot. E.g. the various messages from the attributes are rendered in the *authorized-button* or *unauthorized-button*.\r\n\r\nThe content of the *authorized-button* and *unauthorized-button* slots are overwritten by the *loginMessage*, *authorizedMessage* and *unauthorizedTemplate* attributes. These slots are only useful for styling the messages. To modify the look and feel beyond that, use the *-header* and *-footer* slots.\r\n\r\nSee the [custom buttons demo](https://overhide.github.io/pay2my.app/demo-front-end/custom.html) ([code](/demo-front-end/custom.html)) for examples.\r\n\r\n##### Events\r\n\r\n*pay2myapp-appsell-sku-clicked*\r\n\r\n- see *IPay2MyAppSkuClickedEvent* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts)\r\n\r\n```\r\n export interface IPay2MyAppSkuClickedEvent {\r\n sku: string,\r\n message: string,\r\n signature: string,\r\n from: string,\r\n to: string,\r\n currency: Currency,\r\n imparter: Imparter,\r\n isTest: boolean,\r\n asOf: string,\r\n priceDollars: string,\r\n withinMinutes: string\r\n}\r\n```\r\n\r\n- the event fired by an pay2myapp-appsell component when an appsell SKU deemed authorized by overhide is clicked by the user\r\n- usually safest to route state-changes in response to this event via a back-end — and let the back-end re-validate authorizations\r\n- all necessary information to validate is provided in this event\r\n- âš passing the `asOf` timestamp to your back-end — and having your back-end pass this value to [overhide APIs](https://overhide.io/2020/09/06/remuneration-api.html) when checking authorizations — is an important optimization. Since the *overhide* services already recently checked these transactions as part of this front-end work; the `asOf` timestamp ensures we re-load these resutls from cache and do not get rate-limited in the back-end.\r\n- example:\r\n\r\n```\r\n \r\n```\r\n\r\n*pay2myapp-appsell-topup-outstanding*\r\n\r\n- see *IPay2MyAppSkuTopupOutstandingEvent* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts)\r\n\r\n```\r\nexport interface IPay2MyAppSkuTopupOutstandingEvent {\r\n sku: string,\r\n topup: number\r\n}\r\n```\r\n\r\n- an event fired by an pay2myapp-appsell component when there was an authorization attempt but insufficient funds to authorize\r\n- this even contains the outstanind topup funds required: in US dollars\r\n\r\n### ``\r\n\r\nA very simple widget usually provided in the nav-bar of an application.\r\n\r\nShows the currently logged in address and against which login provider (icon).\r\n\r\nAllows manually refreshing payments and a logout button.\r\n\r\nWhen logged in, clicking the address shows a transaction history.\r\n\r\nWhen logged out, clicking the \"sign-in\" text triggers login.\r\n\r\n##### Attributes\r\n\r\n*hubId*\r\n\r\n- connect to the one and only hub shared among all components in this eco-system\r\n- this is the actual element ID of the [pay2myapp-hub](#pay2myapp-hub-) in the document model\r\n- if the [pay2myapp-hub](#pay2myapp-hub-) is not in the DOM or doesn't have an ID, you'll need to use the `setHub(..)` method (see [setting the hub programatically](#setting-the-pay2myapp-hub-programatically)).\r\n\r\n##### Properties / Methods\r\n\r\nSee *IPay2MyAppStatus* in [/src/components/hub/definitions.ts](/src/components/hub/definitions.ts).\r\n\r\n##### Slots\r\n\r\nN/A\r\n\r\n##### Events\r\n\r\nN/A\r\n\r\n### Local Development\r\n\r\n#### Target a Back-End\r\n\r\nYou can more easily leverge the [overhide.io hosted](https://overhide.io#baas) back-end for your development (and later production). This is why it's there — its raison d'être. This is shown in the [basic](/demo-front-end/basic.html) and [javascript-hub](/demo-front-end/javascript-hub.html) demos.\r\n\r\nIf you already have a back-end or want to write your own, the rest of this section is concerned with that.\r\n\r\nThe [custom](/demo-front-end/custom.html) demo runs against the sample [./demo-back-end](./demo-back-end).\r\n\r\nWe have several ways to run the [./demo-back-end](./demo-back-end) for demo/development purposes. The script constant `BACKEND_CONNECTION_STRING` points at one of the back-end instances, either:\r\n\r\n- https://demo-back-end.azurewebsites.net/api (default)\r\n- http://localhost:8100 (local node.js server)\r\n- http://localhost:7071/api (local AZ function server)\r\n\r\nModify this constant as needed.\r\n\r\n#### Run a Demo Back-End\r\n\r\n> âš The [/demo-front-end/no-back-end.html](/demo-front-end/no-back-end.html) doesn't use a back-end — shows use of widgets without a back-end, the back-end setup can be ignored for this one.\r\n\r\nThe [./demo-back-end](./demo-back-end) folder has all the code for a minimal back-end, whether it runs using node.js locally on your development machine or as an [Azure Function](https://azure.microsoft.com/en-us/services/functions/) (how these demos are hosted).\r\n\r\nTo start running the back-end on your local development machine:\r\n\r\n1. prerequesites:\r\n - node.js\r\n1. open a console to the [./demo-back-end](./demo-back-end) subfolder of this repo\r\n1. `npm install`\r\n1. `npm run dev`\r\n\r\nThe backend is now running.\r\n\r\nYou can try hitting it with:\r\n\r\n- http://localhost:8100/GetSchedule -- this is the demo's fees schedule.\r\n- http://localhost:8100/GetToken -- provides the [overhide token](https://token.overhide.io/swagger.html) for use with `` component.\r\n- There is also the main `http://localhost:8100/RunFeature` endpoint is used by the demo front-ends (see [/demo-front-end/index.js](/demo-front-end/index.js)).\r\n\r\nAlternativelly, if you want to leverage the [Azure Function](https://azure.microsoft.com/en-us/services/functions/) core tooling:\r\n\r\n1. prerequesites:\r\n - node.js\r\n - Azure Functions core tools: `npm install -g azure-functions-core-tools@3 --unsafe-perm true`\r\n1. open a console to the [./demo-back-end](./demo-back-end) subfolder of this repo\r\n1. `npm install`\r\n1. `func start`\r\n\r\nThe you can try hitting the local AZ functions with:\r\n\r\n- http://localhost:7071/api/GetSchedule -- this is the demo's fees schedule.\r\n- http://localhost:7071/api/GetToken -- provides the [overhide token](https://token.overhide.io/swagger.html) for use with `` component.\r\n- There is also the main `http://localhost:7071/api/RunFeature` endpoint is used by the demo front-ends (see [/demo-front-end/index.js](/demo-front-end/index.js)).\r\n\r\n\r\n> ASIDE: deploying to [Azure Functions](https://azure.microsoft.com/en-us/services/functions/): \r\n>\r\n> if you followed the latter, you can deploy to Azure using:\r\n>\r\n> ```\r\n> az login\r\n> func azure functionapp publish \r\n> ```\r\n>\r\n> Then you can hit the functions in Azure, for example, for this demo's name of `demo-back-end` we have: \r\n>\r\n> - https://demo-back-end.azurewebsites.net/api/getschedule -- this is the demo's fees schedule.\r\n> - https://demo-back-end.azurewebsites.net/api/gettoken -- provides the [overhide token](https://token.overhide.io/swagger.html) for use with `` component.\r\n> - There is also the main `https://demo-back-end.azurewebsites.net/api/RunFeature` endpoint is used by the demo front-ends (see [/demo-front-end/index.js](/demo-front-end/index.js)).\r\n\r\n","readmeFilename":"README.md"}
![](\"https://overhide.github.io/overhide-widgets/assets/logo.png\"){kind=logo}
![](\"https://overhide.github.io/pay2my.app/assets/logo.png\"){kind=logo}
![](\"https://overhide.github.io/pay2my.app/assets/widgets.svg\")
![](\"./assets/logo.png\"){kind=logo}
\r\n\t