{"id":16742364,"url":"https://github.com/alexispuga/donations-box","last_synced_at":"2025-07-26T12:03:57.944Z","repository":{"id":57215074,"uuid":"378319555","full_name":"AlexisPuga/donations-box","owner":"AlexisPuga","description":"A widget to ask for donations in a pretty way.","archived":false,"fork":false,"pushed_at":"2022-10-10T17:56:10.000Z","size":249,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T13:25:43.680Z","etag":null,"topics":["donations","web","widget"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexisPuga.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}},"created_at":"2021-06-19T04:05:35.000Z","updated_at":"2024-05-19T07:15:30.000Z","dependencies_parsed_at":"2022-08-24T21:01:35.845Z","dependency_job_id":null,"html_url":"https://github.com/AlexisPuga/donations-box","commit_stats":null,"previous_names":["donations-box/donations-box"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexisPuga%2Fdonations-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexisPuga%2Fdonations-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexisPuga%2Fdonations-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexisPuga%2Fdonations-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexisPuga","download_url":"https://codeload.github.com/AlexisPuga/donations-box/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243809533,"owners_count":20351385,"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":["donations","web","widget"],"created_at":"2024-10-13T01:23:32.681Z","updated_at":"2025-03-16T00:25:35.939Z","avatar_url":"https://github.com/AlexisPuga.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv\u003e\n\t\u003cdiv align='right'\u003e\n\t\t\u003ca href='https://www.npmjs.com/package/donations-box'\u003e\n\t\t\t\u003cimg src='https://img.shields.io/npm/v/donations-box?label=donations-box\u0026color=success\u0026style=flat-square' alt='Current version (NPM)'/\u003e\n\t\t\u003c/a\u003e\n\t\u003c/div\u003e\n\t\u003cdiv align='center'\u003e\n\t\t\u003cimg src='/static/favicon.svg' alt='Donations Box Icon: A pink open box with a white heart.' width='100' height='100'/\u003e\n\t\t\u003ch1\u003eDonations Box\u003c/h1\u003e\n\t\t\u003cp\u003e\u003cstrong\u003eAsk for donations in a pretty way.\u003c/strong\u003e\u003c/p\u003e\n\t\u003c/div\u003e\n\u003c/div\u003e\n\n## About\n[donations-box](/) is a widget for developers who want to list all their donation links, in a single place.\n\n## Features\n- No Javascript required.\n- No frames.\n- Easy to use.\n- Configurable.\n- Minified already.\n- Open Source.\n\n## Installation\n- Via NPM: `npm i donations-box -g`.\n- Via YARN: `yarn global add donations-box`.\n\n## Usage\nTo add this widget to your site:\n1. [Install it](#installation).\n2. Create a new file called `donations-box.config.js`, in the root of your project.\n3. Set your donation links and your desired configurations. [See here](#configuration).\n4. Write `\u003c!-- donations-box --\u003e` where you want to include this widget.\n5. Call the [CLI](#cli) or the [JS](#js) version, during you build process.\n\n**And that's it!**\n\n*If everything works as expected, you should see a new file in `public/css`\ncalled `donations-box.min.css`, and your files where you wrote `\u003c!-- donations-box --\u003e` with the Donations Box's markup.*\n\n### CLI\nRun `donations-box my-file`.\n\n*Where `my-file` is where you want to add the widget to*.\n\n#### Options\nIf you need to change anything, try setting any of the following options:\n```cli\ndonations-box \u003cfiles...\u003e [options]\n\nInject the donations box's markup in the given files.\n\nPositionals:\n  files  Files to inject the donations box's markup. (Globs supported).\n\nOptions:\n  --help       Show help                                              [boolean]\n  --version    Show version number                                    [boolean]\n  --config     Path to your configuration file. See the Configure section in the\n               README file to know more.\n                                 [required] [default: \"donations-box.config.js\"]\n  --assetsDir  Directory in which the assets for this project will be stored.\n               E.g: The css file.                           [default: \"public\"]\n  --token      String to be replaced by the donations box's markup.\n                                             [default: \"\u003c!-- donations-box --\u003e\"]\n```\n\n### JS\n```js\nconst donationsBox = require('donations-box');\n\n(async () =\u003e {\n\n\ttry {\n\n\t\t/**\n\t\t * All CLI positionals, and options are supported, except \"help\", and \"version\". None is optional.\n\t\t * \n\t\t * To know more about each option, run `donations-box --help` from the CLI.\n\t\t * \n\t\t * @param {!object} options\n\t\t * @param {!string} options.files\n\t\t * @param {!string} options.config\n\t\t * @param {!string} options.assetsDir\n\t\t * @param {!string} options.token\n\t\t *\n\t\t * @returns {Promise}.\n\t\t */\n\t\tawait donationsBox({\n\t\t\tfiles: '',\n\t\t\tconfig: '',\n\t\t\tassetsDir: '',\n\t\t\ttoken: ''\n\t\t});\n\n\t}\n\tcatch (\n\t\t/** @type {BuildError|CopyError|InjectionError} */\n\t\texception\n\t) {\n\n\t\t/**\n\t\t * Check exception#name and act accordingly, if you want.\n\t\t * \n\t\t * @example\n\t\t * const {name} = exception;\n\t\t *\n\t\t * if (name === 'BuildError') { console.error('Error building assets.'); }\n\t\t * else if (name === 'CopyError') { console.error('Error copying assets.'); }\n\t\t * else if (name === 'InjectionError') { console.error('Error injecting markup.'); }\n\t\t */\n\n\t}\n\n})();\n```\n\n## Configuration\nConfiguration is done using a `js` or a `json` file, but a `js` file is recommended.\nThe only requirement is that the `js` file should export an object with your configurations.\n\nBelow are the supported configurations *(remember that all the options are used for display purposes)*:\n```js\nmodule.exports = {\n\t/**\n\t * If a truthy value is given, open all links in a new window.\n\t * \n\t * @type {?boolean}\n\t */\n\t'openInNewWindow': false,\n\t/**\n\t * [Optional]\n\t *\n\t * The reason why you're asking for donations.\n\t * \n\t * @type {?string}\n\t */\n\t'headline': '',\n\t/**\n\t * [Optional]\n\t * \n\t * A disclaimer about your donations.\n\t * \n\t * Any HTML tag is valid, but it will be added within a \u003csmall\u003e element.\n\t * \n\t * @type {?string}\n\t */\n\t'disclaimer': '',\n\t/**\n\t * [Only available if headline is set]\n\t * \n\t * If true, always show the donations. Javascript is not used.\n\t * If false, show a button to open the donations. Requires Javascript\n\t * to work.\n\t * If \"auto\", show a button to open the donations if Javascript\n\t * is enabled, otherwise show the donations.\n\t * \n\t * @type {?boolean|?string}\n\t */\n\t'open': true,\n\t/**\n\t * [Only available if headline and disclaimer are set]\n\t * \n\t * Show this number of columns, when the widget is open, on larger screens.\n\t * \n\t * Min value: 1\n\t * Max value: 2\n\t * Default value: 2\n\t * Invalid becomes: 2\n\t * \n\t * @type {?number}\n\t */\n\t'maxColumns': 2,\n\t/**\n\t * The person/company who is asking for donations.\n\t * \n\t * @type {!object}\n\t */\n\t'beneficiary': {\n\t\t/**\n\t\t * The display name for the beneficiary.\n\t\t * \n\t\t * @type {!string}\n\t\t */\n\t\t'alias': 'Donations Box',\n\t\t/**\n\t\t * The url to the beneficiary's website,\n\t\t * or something similar.\n\t\t * \n\t\t * @type {!string}\n\t\t */\n\t\t'href': '/beneficiary.html',\n\t\t/**\n\t\t * Options for the beneficiary's logo/icon.\n\t\t * \n\t\t * @type {!object}\n\t\t */\n\t\t'icon': {\n\t\t\t/**\n\t\t\t * [Available if \"html\" is not set]\n\t\t\t * \n\t\t\t * Url to the image.\n\t\t\t * \n\t\t\t * @type {!string}\n\t\t\t */\n\t\t\t'src': '/favicon.svg',\n\t\t\t/**\n\t\t\t * [Available if \"html\" is not set]\n\t\t\t * \n\t\t\t * Icon's description.\n\t\t\t * \n\t\t\t * @type {!string}\n\t\t\t */\n\t\t\t'alt': 'Donations Box icon',\n\t\t\t/**\n\t\t\t * [Available if \"html\" is not set]\n\t\t\t * \n\t\t\t * Url to visit, on click.\n\t\t\t * \n\t\t\t * @type {!string}\n\t\t\t */\n\t\t\t'href': '/beneficiary.html?icon',\n\t\t\t/**\n\t\t\t * [Optional]\n\t\t\t * \n\t\t\t * Add your own markup to load the image.\n\t\t\t * \n\t\t\t * @type {?string}\n\t\t\t */\n\t\t\t'html': null\n\t\t}\n\t},\n\t/**\n\t * An object containing payment providers as keys,\n\t * and payment specific options as values.\n\t * \n\t * @type {!object}\n\t */\n\t'donations': {\n\t\t/**\n\t\t * Payment options.\n\t\t * \n\t\t * @type {!object[]}\n\t\t */\n\t\t'Stripe': [{\n\t\t\t/**\n\t\t\t * Type of payment: \"one-off\" or \"recurrent\".\n\t\t\t * \n\t\t\t * @type {!string}\n\t\t\t */\n\t\t\t'type': 'one-off',\n\t\t\t/**\n\t\t\t * The url where you actually make the donation.\n\t\t\t * It usually includes the description of your donation\n\t\t\t * (usually referred as \"product\") and some payment options.\n\t\t\t * \n\t\t\t * @type {!string}\n\t\t\t */\n\t\t\t'href': '/donate.html',\n\t\t\t/**\n\t\t\t * The title for your donation/product.\n\t\t\t * \n\t\t\t * @type {!string}\n\t\t\t */\n\t\t\t'title': 'Buy me 1 coffee',\n\t\t\t/**\n\t\t\t * The available amounts for your donation.\n\t\t\t *\n\t\t\t * If \"type\" is set to \"one-off\", it will use the first amount\n\t\t\t * and ignore the others.\n\t\t\t * \n\t\t\t * @type {!object[]|object}\n\t\t\t */\n\t\t\t'amounts': [{\n\t\t\t\t/**\n\t\t\t\t * The url for your donation/product.\n\t\t\t\t * \n\t\t\t\t * Defaults to donation.href.\n\t\t\t\t * \n\t\t\t\t * @type {?string}\n\t\t\t\t */\n\t\t\t\t'href': '/donate.html',\n\t\t\t\t/**\n\t\t\t\t * The requested amount.\n\t\t\t\t * \n\t\t\t\t * @type {!number}\n\t\t\t\t */\n\t\t\t\t'value': 3,\n\t\t\t\t/**\n\t\t\t\t * [Available only on \"recurrent\" donations].\n\t\t\t\t * \n\t\t\t\t * The periodicity of the payment:\n\t\t\t\t * \"Daily\", \"Monthly\", \"Yearly\", ...\n\t\t\t\t * \n\t\t\t\t * The only requirement for this value is that\n\t\t\t\t * is should fill the blanks in the following text:\n\t\t\t\t * \"billed ________\".\n\t\t\t\t * \n\t\t\t\t * @type {?string}\n\t\t\t\t */\n\t\t\t\t'periodicity': 'Daily',\n\t\t\t\t/**\n\t\t\t\t * [Optional]\n\t\t\t\t * \n\t\t\t\t * Options for a QR code.\n\t\t\t\t * \n\t\t\t\t * @type {?object}\n\t\t\t\t */\n\t\t\t\t'qr': {\n\t\t\t\t\t/**\n\t\t\t\t\t * Url for the image.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {!string}\n\t\t\t\t\t */\n\t\t\t\t\t'src': '/img/monero-qr.png',\n\t\t\t\t\t/**\n\t\t\t\t\t * Image's description.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {!string}\n\t\t\t\t\t */\n\t\t\t\t\t'alt': 'Donations Box\\'s Monero QR Code',\n\t\t\t\t\t/**\n\t\t\t\t\t * [Optional]\n\t\t\t\t\t * \n\t\t\t\t\t * A valid img[srcset] attribute value.\n\t\t\t\t\t * \n\t\t\t\t\t * Useful to show different images on retina displays,\n\t\t\t\t\t * for example.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {?string}\n\t\t\t\t\t */\n\t\t\t\t\t'srcset': '/img/monero-qr.png 2x',\n\t\t\t\t\t/**\n\t\t\t\t\t * If a truthy value is given, the qr code will\n\t\t\t\t\t * appear on focus/hover.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {?boolean} \n\t\t\t\t\t */\n\t\t\t\t\t'animate': false\n\t\t\t\t},\n\t\t\t\t/**\n\t\t\t\t * Options for the used currency.\n\t\t\t\t *\n\t\t\t\t * Since this value could get repetitive, it's\n\t\t\t\t * recommended to use a javascript file and\n\t\t\t\t * use a variable here instead. Maybe future\n\t\t\t\t * versions will allow setting a string here,\n\t\t\t\t * but for now it requires an object.\n\t\t\t\t * \n\t\t\t\t * @type {!object}\n\t\t\t\t */\n\t\t\t\t'currency': {\n\t\t\t\t\t/**\n\t\t\t\t\t * The symbol for the currency.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {?string}\n\t\t\t\t\t */\n\t\t\t\t\t'symbol': '$',\n\t\t\t\t\t/**\n\t\t\t\t\t * The name of the currency.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {!string}\n\t\t\t\t\t */\n\t\t\t\t\t'name': 'Dollars',\n\t\t\t\t\t/**\n\t\t\t\t\t * The abbreviation for the currency's name.\n\t\t\t\t\t * \n\t\t\t\t\t * @type {!string}\n\t\t\t\t\t */\n\t\t\t\t\t'abbr': 'USD'\n\t\t\t\t}\n\t\t\t}]\n\t\t}]\n\t}\n};\n```\n## License\nThis project is under the [MIT License](LICENSE), unless otherwise stated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexispuga%2Fdonations-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexispuga%2Fdonations-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexispuga%2Fdonations-box/lists"}