{"id":14965738,"url":"https://github.com/thealphadollar/salvator","last_synced_at":"2025-10-25T12:30:39.339Z","repository":{"id":50083285,"uuid":"137408799","full_name":"thealphadollar/salvator","owner":"thealphadollar","description":"Salvator: The Saviour, When You Forget Birthdays","archived":false,"fork":false,"pushed_at":"2022-12-07T14:21:32.000Z","size":428,"stargazers_count":10,"open_issues_count":10,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-27T09:08:51.330Z","etag":null,"topics":["automation","birthdays","bot","forget-birthdays","hacktoberfest","headless-chrome","javascript","messenger","puppeteer"],"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/thealphadollar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-14T21:00:52.000Z","updated_at":"2024-01-19T10:10:52.000Z","dependencies_parsed_at":"2023-01-24T17:31:57.496Z","dependency_job_id":null,"html_url":"https://github.com/thealphadollar/salvator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fsalvator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fsalvator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fsalvator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thealphadollar%2Fsalvator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thealphadollar","download_url":"https://codeload.github.com/thealphadollar/salvator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238137863,"owners_count":19422716,"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":["automation","birthdays","bot","forget-birthdays","hacktoberfest","headless-chrome","javascript","messenger","puppeteer"],"created_at":"2024-09-24T13:35:13.337Z","updated_at":"2025-10-25T12:30:34.061Z","avatar_url":"https://github.com/thealphadollar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Salvator: The Saviour, When You Forget Birthdays\n\n[![Join the chat at https://gitter.im/salvator_/Lobby](https://badges.gitter.im/salvator_/Lobby.svg)](https://gitter.im/salvator_/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n## What is Salvator?\nSalvator is a bot which uses puppeteer to scrape the list of birthdays from facebook and sends them a personal\nmessage.\n\nIt also sends the user an email notification with the list of birthdays and their profile link.\n\n![puppeteer-salvator cli in action!!](screenshots/salvator.gif)\n\n\n## How does it work?\nPuppeteer uses a headless browser to navigate to `facebook.com/login` and using the credentials from the `.env` file,\nlogs in. There after it navigates to the birthday events page, scrapes the profile links for birthday people, forms\nthe messenger link using it and sends them a personalised message.\u003cbr/\u003e\nE.g `Hey thealphadollar! Happy Birthday :D`, if user's first name is \"thealphadollar\".The message is randomized from a stored list.\n\nTo avoid sending multiple wishes, the program creates a json file with a timestamp and a list with the links already wished. When the file is read, if the timestamp matches the day, the redundancies are avoided.\n\n## Install\nSalvator can be installed using npm or source.\n\n **NOTE: puppeteer-salvator installs Chromium(102 MB) along with it. If you have already Chromium installed, use the `--ignore-scripts` option.**\n\n* ### Install using npm\n    1. [Install npm](https://www.npmjs.com/get-npm)\n    2. `npm install -g puppeteer-salvator`\n    \u003cbr /\u003e\n    ***OR***\n    \u003cbr/\u003e`npm install -g puppeteer-salvator --ignore-scripts` *(without Chromium)*\n\n* ### Build using source (**RECOMMENDED**)\n    1. `git clone https://www.github.com/thealphadollar/salvator`\n    2. `cd salvator`\n    3. [Install npm](https://www.npmjs.com/get-npm)\n    4. `npm install` (this step installs all the dependencies)\n    5. `npm link` - to link the CLI tool so that it can be used globally in your system.\n\n## Using CLI tool locally\nFollow the steps given below in order to run the **puppeteer-salvator** tool globally in your terminal:\n\n1. Go to the project folder and run `npm link` in your terminal. Creates a *symlink* in the global folder `{prefix}/lib/node_modules/\u003cpackage\u003e` to your project.\n2. Open a new terminal and run `puppeteer-salvator` from anywhere(not necessarily the project folder).\n3. In-case you are done testing and want to remove the *symlink* from the global folder, run `npm unlink`.\n\n**NOTE: In case of any errors related to launching headless chrome, [install google-chrome-stable](https://www.linuxbabe.com/ubuntu/install-google-chrome-ubuntu-16-04-lts).\n It'll resolve all the dependency issues.**\n\n## Using Salvator\nBefore running Salvator, the following environment variables must be set to avail full functionality of the client:\n```$xslt\nFB_ID=\u003cyour login email/phone for facebook\u003e\nFB_PASS=\u003cyour login password for facebook\u003e\nEMAIL=\u003cnotification will be sent from this address\u003e\nEMAIL_PASS=\u003cpassword for the email\u003e\nMAILTO=\u003cnotification will be sent to this address\u003e\n```\n**RECOMMENDED** : Create a `.env` file in the `salvator` folder with the above mentioned environment variables. Or you can do it using our CLI tool **puppeteer-salvator** by running the command `puppeteer-salvator env`.\n\n**NOTE** : You also need to [enable access to less secure apps](https://support.google.com/a/answer/6260879?hl=en) in your GMail account (the\nclient only supports sending from gmail accounts).\n\n\n\nAfter you are done with *installation*, Salvator can be launched manually using the commands :\n- `puppeteer-salvator run`, if installed from npm \n- `node index.js`, from source directory\n\nHowever, it is recommended to [add a cronjob](https://www.cyberciti.biz/faq/how-do-i-add-jobs-to-cron-under-linux-or-unix-oses/) to automatically launch the client at the desired time,\nfavorable 00:05 hours. By this time facebook updates the list of birthdays and hence you could be among the first to\n wish.\n\nFor example, the below cronjob launches the script everyday at 00:05 (local system timezone is followed) and logs the sys.stdout into cron.log\n```\n5 0 * * * nodejs /path/to/salvator/index.js \u003e\u003e ~/cron.log\n```\n\nThe cronjob can be added by executing the file cron.sh\n\nMake sure the file has appropriate permissions and if not run the following\n```\nchmod a+x cron.sh\n```\n## Puppetter Salvator CLI tool\n\nThe CLI tool provides an interface to interact with the CLI tool and utilize its functionality. The following set of commands are provided by the tool:\n* `puppeteer-salvator run` : Run the automated Birthday wish script\n* `puppeteer-salvator env` : Load environment variables in .env file(fb_id, fb_pass, email, ..)\n* `puppeteer-salvator cron` : Add a cronjob delete a cronjob, view all cronjobs\n* `puppeteer-salvator bth` :  Show all the birthdays for the current\n\n## Contributing\nContributions are welcome, please look in the issues tab to contribute.\n*   VSCode is recommended as the editor for this project.\n*   Install eslint plugin for vscode. Use this [video][1] to setup eslint-prettier for vscode.\n*   Please follow [JSDoc][3] for your submitted code. Use [DocumentThis][2] plugin      if required.\n*   Please read CONTRIBUTING.md guide to know more.\n*   Write tests for complicated components and modules.\n\n[1]: https://www.youtube.com/watch?v=YIvjKId9m2c\n[2]: https://marketplace.visualstudio.com/items?itemName=joelday.docthis\n[3]: http://usejsdoc.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthealphadollar%2Fsalvator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthealphadollar%2Fsalvator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthealphadollar%2Fsalvator/lists"}