3a26343cb7
* Add pytest suite and wire it into CI Stands up the first automated tests for the repo (151 tests) and turns on the CI test step. - Lift slack-bot handlers out of create_app() closures to module level so they're unit-testable; create_app is now a thin Bolt-wiring layer. No behavior change (handler entrypoints and create_app signature unchanged). - tests/ mirrors src/: shared layer (schedule, blocks, 3CX client, ring_scheduler, secrets) + all four Lambdas (pay math, drop/swap/pick/ admin/register/rate, pickup button, roster sync, queue scheduler). - All boundaries mocked: DynamoDB/SES/Secrets via moto, 3CX HTTP via responses, Slack via fakes, time via freezegun. No real network/AWS. - pyproject.toml pytest config (pythonpath=src/shared, importlib mode); per-package conftest loads each app.py under a unique name to avoid the four-app.py collision. tests/requirements.txt for test-only deps. - ci.yaml: run-tests: true (reusable workflow auto-installs deps) and lint the tests dir too. - README Testing section. Closes #85 * Add least-privilege permissions block to CI workflow Resolves the CodeQL actions/missing-workflow-permissions alert: the CI workflow now restricts GITHUB_TOKEN to contents: read (it only checks out, lints, and runs tests). * Stop logging extension numbers in 3CX queue updates Resolves 3 high CodeQL py/clear-text-logging-sensitive-data alerts: the queue/ring-group forwarding logs no longer include the routed extension values (closed/holiday/extension). Non-sensitive context (resource id, queue number) is retained.
5.4 KiB
After-Hours Shift Manager
Slack bot for managing after-hours on-call shifts at Sea Haven Industries. Employees can pick up, drop, and swap shifts directly from Slack. Changes automatically update 3CX queue routing via the integrated ring scheduler.
How It Works
A recurring weekly schedule assigns employees to after-hours phone duty. Weekend shifts are split into Day (8am-5pm) and Night (5pm-8am). Any unassigned shift shows as Available in Slack with a pickup button. When someone picks up or drops a shift for today, the 3CX queue is updated immediately. Future changes take effect when the ring scheduler runs at 8am daily and 5pm on weekends.
The weekly schedule post is updated live when shifts change, and the previous week's post is automatically deleted when the new one goes out.
Slack Commands
| Command | Description |
|---|---|
/oncall |
Show this week's schedule |
/oncall next |
Show next week's schedule |
/oncall pick <date> |
Pick up an available shift |
/oncall drop <date> |
Drop your shift (marks it available) |
/oncall swap <date> @person |
Hand your shift to someone else |
/oncall register <ext> |
Link your Slack account to your phone extension |
/oncall roster |
Show all employees and their link status |
/oncall pay |
Show last week's bonus pay summary |
/oncall rate |
Show current shift pay rates |
/oncall rate default <amount> |
Set the default per-shift rate |
/oncall rate <ext> <amount> |
Set a per-person shift rate |
/oncall help |
Show help |
Admin Commands
Available to users listed in admin_users in the CONFIG record:
| Command | Description |
|---|---|
/oncall admin override <date> <ext> |
Assign a shift to an extension |
/oncall admin open <date> |
Mark a shift as open |
/oncall admin clear <date> |
Remove override (revert to weekly) |
/oncall admin roster add <ext> <name> |
Add an employee to the roster |
/oncall admin roster remove <ext> |
Remove an employee |
/oncall admin roster rename <ext> <name> |
Rename an employee |
Dates accept: today, tomorrow, monday-sunday, 4/5, 2026-04-05
Architecture
- Runtime: Python 3.12 on AWS Lambda (arm64)
- Data: DynamoDB single-table (
afterhours-shifts) - IaC: AWS SAM (
template.yaml) with shared Lambda Layer - Slack: Slack Bolt framework with
/oncallslash command - 3CX Integration: Queue routing updated directly via 3CX Queue XAPI
- Secrets: AWS Secrets Manager (
afterhours-shift-manager/*)
Lambda Functions
| Function | Trigger | Purpose |
|---|---|---|
afterhours-shift-manager |
API Gateway (POST /slack/events) | Slack bot — handles /oncall commands and interactive buttons |
afterhours-weekly-post |
EventBridge (Monday 7am ET) | Posts weekly schedule to Slack, sends pay report email |
afterhours-roster-sync |
EventBridge (daily 6am ET) | Syncs employee roster from 3CX |
afterhours-ring-scheduler |
EventBridge (daily 8am ET + weekend 5pm ET) | Updates 3CX queue routing based on who's on shift |
Project Layout
src/
slack-bot/ Slack Bolt Lambda (handler + app)
weekly-post/ Monday schedule + pay post
roster-sync/ Daily 3CX roster sync
ring-scheduler/ 3CX queue routing updates
shared/ Lambda Layer (schedule, blocks, 3CX client, secrets)
tests/ pytest suite (mirrors src/, one dir per Lambda + shared)
DynamoDB Schema
Single table with PK / SK keys:
| PK | SK | Description |
|---|---|---|
ROSTER |
<extension> |
Employee: name, extension, slack_user_id |
WEEKLY |
<DayName> |
Default weekly schedule: extension, name |
OVERRIDE |
<YYYY-MM-DD> |
Date override from pickup/drop (or OPEN) |
SCHEDULE_POST |
<channel_id> |
Current schedule message timestamp |
PAY |
<YYYY-MM-DD> |
Weekly pay record (Monday date key) |
CONFIG |
CONFIG |
Settings: shift_rate, fallback_extension, admin_users |
Secrets Manager
| Secret | Description |
|---|---|
afterhours-shift-manager/slack-bot-token |
Slack bot OAuth token (xoxb-...) |
afterhours-shift-manager/slack-signing-secret |
Slack app signing secret |
afterhours-shift-manager/3cx-domain |
3CX FQDN (e.g. company.3cx.us) |
afterhours-shift-manager/3cx-client-id |
3CX OAuth2 client ID |
afterhours-shift-manager/3cx-client-secret |
3CX OAuth2 client secret |
Deployment
Merges to main are automatically deployed via GitHub Actions using reusable SAM workflows from the Sea Haven org.
For manual deploys:
sam build
sam deploy
Testing
Unit tests use pytest with all external boundaries mocked — DynamoDB / SES /
Secrets Manager via moto, 3CX HTTP via responses, Slack via fakes, and time
via freezegun. No test touches the network or real AWS.
python -m venv .venv && source .venv/bin/activate
pip install -r tests/requirements.txt # test-only deps
pip install -r src/slack-bot/requirements.txt \
-r src/weekly-post/requirements.txt \
-r src/shared/requirements.txt # runtime deps the imports need
pytest
Each Lambda has its own app.py, so the per-package conftest.py loads each one
under a unique module name (importlib mode) to avoid collisions. CI runs the same
suite on every PR via the org ci-python-sam workflow (run-tests: true).
See SETUP.md for full deployment and Slack app creation instructions.