{"id":13433667,"url":"https://github.com/Glench/ExtPay","last_synced_at":"2025-03-17T13:30:42.849Z","repository":{"id":37683239,"uuid":"327994237","full_name":"Glench/ExtPay","owner":"Glench","description":"The JavaScript library for ExtensionPay.com — payments for your browser extensions, no server needed.","archived":false,"fork":false,"pushed_at":"2025-02-27T15:43:48.000Z","size":2433,"stargazers_count":575,"open_issues_count":7,"forks_count":69,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-03-16T12:09:52.433Z","etag":null,"topics":["browser-extension","chrome-extension","firefox-extension","javascript-library","monetisation","monetise","monetization","monetize","payments","web-extensions"],"latest_commit_sha":null,"homepage":"https://extensionpay.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Glench.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-08T19:30:31.000Z","updated_at":"2025-03-12T13:09:17.000Z","dependencies_parsed_at":"2023-01-31T16:16:00.227Z","dependency_job_id":"41459f13-d779-4681-ae3f-0a75946f7eb0","html_url":"https://github.com/Glench/ExtPay","commit_stats":{"total_commits":74,"total_committers":3,"mean_commits":"24.666666666666668","dds":"0.027027027027026973","last_synced_commit":"38c2d94de5c174e80178e98bf17bb88ef484fe5a"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glench%2FExtPay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glench%2FExtPay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glench%2FExtPay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glench%2FExtPay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Glench","download_url":"https://codeload.github.com/Glench/ExtPay/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244041366,"owners_count":20388225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-extension","chrome-extension","firefox-extension","javascript-library","monetisation","monetise","monetization","monetize","payments","web-extensions"],"created_at":"2024-07-31T02:01:32.477Z","updated_at":"2025-03-17T13:30:42.818Z","avatar_url":"https://github.com/Glench.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Libraries and Frameworks"],"sub_categories":[],"readme":"# ExtPay.js — Monetize browser extensions with payments\nThe JavaScript library for [ExtensionPay.com](https://extensionpay.com), a service to easily add payments to browser extensions. So far ExtensionPay has earned extension creators **over $300k and counting**!\n\n```js\n// Example code\n// your-extension/background.js\nconst extpay = ExtPay('your-extension-id');\nextpay.startBackground();\n\nextpay.getUser().then(user =\u003e {\n    if (user.paid) {\n        // ...\n    } else {\n        extpay.openPaymentPage()\n    }\n})\n```\n\nBelow are directions for using this library in your browser extension. If you learn better by example, you can also view the code for a **[sample extension](sample-extension-mv3/)**. This library uses [Mozilla's webextension-polyfill library](https://github.com/mozilla/webextension-polyfill) internally for compatability across browsers which means it should work on almost all modern browsers.\n\n\u003e \"It hasn't even been 1 year yet and I'm already going to **pass $4,000 in annual subscriptions on an extension that I never in a million years thought I would be able to make a penny from**. Thanks so much for creating this tool! I would not have even tried to monetize if I had to use Stripe directly, and you made it so easy. **It took less than an hour to set it up and test it**. Definitely have plans to create more extensions now that I know how **easy it is to monetize them**.\" - David, Neobuyer extension\n\n  1. [Install](#1-install)\n  2. [Configure your `manifest.json`](#2-configure-your-manifestjson)\n  3. [Add `ExtPay` to `background.js` (required!)](#3-add-extpay-to-backgroundjs-required)\n  4. [Use `extpay.getUser()` to check a user's paid status](#4-use-extpaygetuser-to-check-a-users-paid-status)\n      * [`user` object properties](#user-object-properties)\n  5. [Use `extpay.openPaymentPage()` to let the user pay](#5-use-extpayopenpaymentpage-to-let-the-user-pay)\n  6. [Use `extpay.onPaid.addListener()` to run code when the user pays](#6-use-extpayonpaidaddlistener-to-run-code-when-the-user-pays)\n  7. [Use `extpay.openPaymentPage()` to let the user manage their subscription preferences](#7-use-extpayopenpaymentpage-to-let-the-user-manage-their-subscription-preferences)\n  8. [Use `extpay.openTrialPage()` to let the user sign up for a free trial](#8-use-extpayopentrialpage-to-let-the-user-sign-up-for-a-free-trial)\n  9. [Use `extpay.openLoginPage()` to let the user log in if they've paid already](#9-use-extpayopenloginpage-to-let-the-user-log-in-if-theyve-paid-already)\n\n**Note**: ExtPay.js doesn't contain malware or track your users in any way. This library only communicates with ExtensionPay.com servers to manage users' paid status.\n\nIf you like this library, please star it! ⭐️ It helps us out :)\n\n## 1. Install\n\nCopy the [dist/ExtPay.js](dist/ExtPay.js) file into your project, or, if you're using a bundler (like Webpack or Rollup):\n\n```bash\nnpm install extpay --save\n```\n\n\n## 2. Configure your `manifest.json`\nExtPay needs the following configuration in your `manifest.json` (for both manifest v2 and v3):\n\n```json\n{\n    \"permissions\": [\n      \"storage\"\n    ]\n}\n```\n\nExtPay will not show a scary permission warning when users try to install your extension.\n\nNote: For Firefox, you may have to include `\"https://extensionpay.com/*\"` in your extension manifest's \"permission\" for ExtPay to work properly.\n\nIf you have a `\"content_security_policy\"` in your manifest or get a `Refused to connect to 'https://extensionpay.com...'` error, you'll have to add `connect-src https://extensionpay.com` to your extension's content security policy. \u003ca href=\"https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy\"\u003eSee Mozilla's documentation for more details\u003c/a\u003e.\n\n\n## 3. Add `ExtPay` to `background.js` (required!)\n\nYou need to put `ExtPay` in your background file, often named something like `background.js`. If you don't include `ExtPay` in your background file it won't work correctly. If you're using a bundler you can `import 'ExtPay'` or `require('ExtPay')` right in your `background.js`.\n\nWith either Manifest V3 or Manifest V2 you'll need to **[sign up and register an extension](https://extensionpay.com)**. When you register an extension you'll create an extension id that you'll use when initializing `ExtPay`. We'll use `sample-extension` as the extension id in the following examples.\n\n### Manifest V3\n\n```json\n{\n    \"background\": {\n        \"service_worker\": \"background.js\"\n    }\n}\n```\n\n```js\n// background.js\n\nimportScripts('ExtPay.js') // or `import` / `require` if using a bundler\n\nvar extpay = ExtPay('sample-extension'); // Careful! See note below\nextpay.startBackground(); \n```\n\n**Note about service workers**: In the example above `extpay` will become undefined when accessed in service worker callbacks. To use `extpay` in service worker callbacks, redeclare it like so:\n\n```js\nchrome.storage.local.get('foo', function() {\n    var extpay = ExtPay('sample-extension');\n    // ...\n})\n```\nMake sure not to use `extpay.startBackground()` in callbacks — it should only be called once.\n\n### Manifest V2\n\nIf you're not using a bundler, add `ExtPay.js` to `manifest.json`:\n```json\n{\n    \"background\": {\n        \"scripts\": [\"ExtPay.js\", \"background.js\"]\n    }\n}\n```\n\n\n```js\n// background.js\nconst extpay = ExtPay('sample-extension')\nextpay.startBackground();\n```\n\n\n\n\n## 4. Use `extpay.getUser()` to check a user's paid status\n\nThis method makes a network call to get the extension user's paid status and returns a `user` object.\n```js\nextpay.getUser().then(user =\u003e {\n    if (user.paid) {\n        // ...\n    } else {\n        // ...\n    }\n})\n```\nor use `await`:\n```js\nasync function foo() {\n    const user = await extpay.getUser();\n    if (user.paid) {\n        // ...\n    }\n}\n```\nIt is possible for `extpay.getUser()` to throw an error in case of a network failure. Please consider this possibility in your code e.g. `extpay.getUser().then(/* ... */).catch(/* handle error */)`\n\nThe `user` object returned from `extpay.getUser()` has the following properties:\n\n### `user` object properties\n| property | description |\n| --- | --- |\n| `user.paid` | `true` or `false`. `user.paid` is meant to be a simple way to tell if the user should have paid features activated. For subscription payments, `paid` is only true if `subscriptionStatus` is `active`. |\n| `user.paidAt` | `Date()` object that the user first paid or `null`.|\n| `user.email` | The user's email if there is one or `null`.|\n| `user.installedAt` | `Date()` object the user installed the extension. |\n| `user.trialStartedAt` | `null` or `Date()` object the user confirmed their free trial. |\n| **subscription only**| |\n| `user.subscriptionStatus` | One of `active`, `past_due`, or `canceled`. `active` means the user's subscription is paid-for. `past_due` means the user's most recent subscription payment has failed (expired card, insufficient funds, etc). `canceled` means that the user has canceled their subscription and the end of their last paid period has passed. [You can read more about how subscriptions work here](/docs/how_subscriptions_work.md). |\n| `user.subscriptionCancelAt` | `null` or `Date()` object that the user's subscription is set to cancel or did cancel at. |\n\n## 5. Use `extpay.openPaymentPage()` to let the user pay\n\nOpens a browser popup where the user can pay to upgrade their status.\n```js\nextpay.openPaymentPage()\n```\nThe payment page looks like this:\n\n![popup screenshot](docs/popup_screenshot.png)\n\nNote: `extpay.openPaymentPage()` can fail to open the popup if there is a network error. Please consider this possibility in your code.\n\nIt is best to open the payment page when the user has a clear idea of what they're paying for.\n\nWhile testing, use your ExtensionPay email to test payments without entering credit card information. Reinstall the extension to reset back to an unpaid user.\n\nDepending on how you configure your extension, users that have paid before can log in to activate their paid features on different browsers, profiles, or after uninstalling/reinstalling.\n\n\n## 6. Use `extpay.onPaid.addListener()` to run code when the user pays\n\nIf you want to run some code when your user pays for the first time, use `extpay.onPaid.addListener()`:\n\n```js\nextpay.onPaid.addListener(user =\u003e {\n    console.log('user paid!')\n})\n```\n\nTo use this feature, you will need to include the following content script configuration in your `manifest.json`:\n\n```json\n{\n    \"content_scripts\": [\n        {\n            \"matches\": [\"https://extensionpay.com/*\"],\n            \"js\": [\"ExtPay.js\"],\n            \"run_at\": \"document_start\"\n        }\n    ]\n}\n```\n\nThe content script is required to enable `extpay.onPaid` callbacks. It will add a permissions warning when installing your extension. If you're using a bundler, you can create a file called something like `ExtPay_content_script.js` that only contains `import 'ExtPay'` or `require('ExtPay')` and use that in the `\"js\"` field above.\n\nYou can add as many callback functions as you want.\n\nNote: `onPaid` callbacks will be called after a user pays as well as after a user \"logs in\" (e.g. activates their paid account on a different browser/profile/install). This may change in the future -- if you'd like this to work differently, please contact me with a detailed explanation of your use case :)\n\n\n## 7. Use `extpay.openPaymentPage()` to let the user manage their subscription preferences\n\nIf your extension is configured for subscription payments, you can let the user manage their subscription from within the extension with the same function you used to let them pay:\n\n```js\nextpay.openPaymentPage()\n```\n\nThe subscription management page looks something like this:\n\n\u003cimg src=\"docs/subscription_management_screenshot.png\" alt=\"Screenshot of example subscription management page.\" width=\"400\"\u003e \n\nNote: please read the **[detailed docs on subscriptions here](/docs/how_subscriptions_work.md)**.\n\n\n## 8. Use `extpay.openTrialPage()` to let the user sign up for a free trial\n\nIf you want to give your users a trial period of your extension, you can use `extpay.openTrialPage()`, which looks something like this:\n\n\u003cimg src=\"docs/trial_page_screenshot.png\" alt=\"Screenshot of trial page\" width=\"400\"\u003e \n\nThe user will be sent an email with a link that they can use to start their free trial. Once the user clicks the link, you can use the `trialStartedAt` property from `extpay.getUser()` in your extension to check if the trial has expired.\n\nFor example, if you wanted a 7 day trial period, you could use a check like this:\n\n```js\nconst extpay = ExtPay('sample-extension');\nextpay.getUser().then(user =\u003e {\n    const now = new Date();\n    const sevenDays = 1000*60*60*24*7 // in milliseconds\n    if (user.trialStartedAt \u0026\u0026 (now - user.trialStartedAt) \u003c sevenDays) {\n        // user's trial is active\n    } else {\n        // user's trial is not active\n    }\n})\n```\n\nNote that `extpay.openTrialPage(displayText)` takes an optional string argument that is displayed to the user on the trial page. For example, `extpay.openTrialPage('7-day')` would change the trial prompt from `Enter an email to start your free trial` to `Enter an email to start your *7-day* free trial`. This is meant to give your users a better idea of what they're signing up for.\n\nYou can also use `extpay.onTrialStarted.addListener()` to run functions when the user's trial starts. Like `onPaid`, you need to include the following in your `manifest.json` to make it work:\n\n```json\n{\n    \"content_scripts\": [\n        {\n            \"matches\": [\"https://extensionpay.com/*\"],\n            \"js\": [\"ExtPay.js\"],\n            \"run_at\": \"document_start\"\n        }\n    ]\n}\n```\n\n## 9. Use `extpay.openLoginPage()` to let the user log in if they've paid already\n\nA page will open that will allow the user to enter the email they paid with to receive a magic login link. This page can also be accessed through the normal payment screen.\n\n## Contributing\n\n1. `npm install`\n2. Edit `ExtPay.dev.js`\n3. `npm run dev`\n4. `npm run dist` before committing changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGlench%2FExtPay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGlench%2FExtPay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGlench%2FExtPay/lists"}