From bca3f75a9c11c3fb149c2af542621980214e3f96 Mon Sep 17 00:00:00 2001 From: sherl Date: Mon, 21 Apr 2025 21:09:35 +0200 Subject: [PATCH] chore: add a README --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/README.md b/README.md index 3bd47f6..32679f4 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,45 @@ # stolat +Hackable script which can run your code when someone is getting closer to their birthday. +## What can it do? +Anything that you're willing to implement yourself. After preconditions for sending a notification are met, the script will try to execute configured script inside the `scripts` directory. +This means, that if you have an existing script/workflow for notifying users, say, through XMPP messages, SMS, e-mail, IRC, and so on, you can easily import it and run it. + +## Why bother using it? +If your workflow is a little bit unorthodox, but you already have a working setup, then *stolat* with the help of cron checks the brithdays for you. +This is exceptionally useful if you manage a multi-user service/server. You don't need to worry about checking the date, but still have the flexibility over what should be ran when it's time to notify a user. + +## How does it work? +With the power of cron, you set up a daily cron-job, e.g. at 8 AM, which will check if any of the people whose birthdays have been entered is close to their birthday. Then, a script of yours gets passed some arguments and is executed. What you do with this data is up to you. +People willing to get notified can request additional reminders, for example 3 days before a birthday. By default, only on the day of the birthday a notification is sent. This is configurable in the `list.toml` file. + +## Sample config +A sample config has been put into `list.example.toml`. +Here's an excerpt: + +``` +preferences = [ + {user="bob@localhost", channels=[0]}, + {user="alice@localhost", channels=[0], "additional_reminders"=[1, 7]} +] + +birthdays = [ + {name="Bob", date="2000-01-01", to_notify=["alice@localhost"]}, + {name="Alice", date="2000-01-23", to_notify=["bob@localhost"]} +] + +actions = [ + {id=0, name="print information", name_of_script="sample_script.py", startup_function="print_v1_data"} +] +``` + +Above allows Bob to receive notifications about Alice's birthdays, and Alice to get reminded about Bob's birthday on the day of his birthday, but also 1 and 7 days prior. +When they're meant to be notified, a method inside `sample_script.py` (in the `scripts` directory) called `print_v1_data` will be ran, with the API version and appropriate data passed. +For API version "v1" these are: notifyee's username, name of the person, age, days until birthday (0 if it's the day of the birthday), and birthday date. + +For the cron job, a sample config would look something like: +``` +0 7 * * * python3 /path/to/stolat/notify.py +``` +This would make it run every day at 7 o'clock every day. +It's important to make it run once per day, otherwise users will get notified as many times, as the script is run!