Metadata-Version: 2.4
Name: hr-birthday-letters
Version: 0.1.0
Summary: Generate milestone birthday letters for employees and deliver them through managers.
Author: HR Automation
License-Expression: MIT
Keywords: hr,birthday,letters,automation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: office
Requires-Dist: pywin32>=306; platform_system == "Windows" and extra == "office"

# HR Birthday Letter Generator

A simple Python project to generate milestone birthday letters for employees and deliver them through managers.
It can be used from the command line or through a small desktop app for office users.

## Project structure

- `generate_birthday_letters.py` - package entrypoint script
- `birthday_letters_app.py` - desktop app entrypoint
- `Start Birthday Letters.bat` - Windows launcher for the desktop app
- `hr_birthday_letters/` - package source code
- `hr_birthday_letters/templates/` - language-specific mail cover and PDF letter templates
- `employees.csv` - sample employee data file
- `tests/` - unit tests
- `output/` - generated mail cover text files and PDF letters are saved here by default

## CSV Format

Required columns:
- `Name`
- `DateOfBirth` (YYYY-MM-DD)
- `Manager`
- `Language` (matches a template file such as `en.txt` or `nl.txt`)

Optional columns:
- `ManagerEmail` (required when creating Outlook mails)
- `EmployeeEmail`
- `Department`
- `Location`

Example:

```csv
Name,DateOfBirth,Manager,ManagerEmail,Language,Department,Location
Alice Johnson,1996-05-28,Michael Smith,michael.smith@example.com,en,Engineering,New York
Ella Rodriguez,2001-05-28,Michael Smith,michael.smith@example.com,nl,Engineering,New York
```

## Templates

Templates are plain text files stored in `hr_birthday_letters/templates/` by default.
The employee `Language` value selects matching templates for both outputs:

- The mail cover text uses `hr_birthday_letters/templates/cover/<language>.txt`
- The PDF birthday letter uses `hr_birthday_letters/templates/letter/<language>.txt`

For example, `en` uses both:

- `hr_birthday_letters/templates/cover/en.txt`
- `hr_birthday_letters/templates/letter/en.txt`

The cover text is high level and addressed to the manager. The PDF letter is addressed to the employee whose birthday milestone is being recognized.

Available placeholders:

- `$date`
- `$manager`
- `$manager_email`
- `$employee_name`
- `$employee_email`
- `$birthday`
- `$age`
- `$department`
- `$location`
- `$language`

## Install

Use Python 3.9+ and install the package in editable mode:

```powershell
cd C:\Users\KRIJDI01\hr-birthday-letters
python -m pip install -e .
```

For Outlook desktop integration on Windows, install the optional office dependency:

```powershell
python -m pip install -e ".[office]"
```

## Desktop app

Start the app:

```powershell
.\Start Birthday Letters.bat
```

Or run it with Python:

```powershell
python birthday_letters_app.py
```

Or use the installed script:

```powershell
hr-birthday-letters-ui
```

The app lets an office user:

- Select the employee CSV, output folder, and template folder
- Generate mail cover text files and PDF birthday letters
- Maintain cover and PDF letter templates by language
- Create Outlook drafts with the PDF attached
- Open Outlook mails for review or send immediately after confirmation

## Run

```powershell
python generate_birthday_letters.py employees.csv
```

Or use the installed CLI script:

```powershell
hr-birthday-letters employees.csv
```

To specify a different output directory:

```powershell
hr-birthday-letters employees.csv --output-dir letters
```

To use a custom template directory:

```powershell
hr-birthday-letters employees.csv --template-dir templates
```

To create Outlook drafts from the command line:

```powershell
hr-birthday-letters employees.csv --create-outlook-drafts
```

Other Outlook options:

```powershell
hr-birthday-letters employees.csv --open-outlook-mails
hr-birthday-letters employees.csv --send-outlook-mails
```

The custom directory should use the same layout:

```text
templates/
  cover/
    en.txt
    nl.txt
  letter/
    en.txt
    nl.txt
```

## Test

Install the test dependencies first:

```powershell
python -m pip install -e .[test]
python -m pytest
```

## How it works

- Reads employee rows from a CSV file
- Computes each employee's age as of today
- Generates the cover text and PDF letter only when the age is a positive multiple of 5
- Selects cover and letter templates using the employee's `Language` value
- Saves one manager-facing mail cover text file per eligible employee
- Saves one employee-facing birthday letter PDF per eligible employee
- Uses `ManagerEmail` to create Outlook mails with the PDF attached
