Three new opt-in integration connectors that plug into the existing
`app/integrations/base.py:BaseConnector` pattern and the integrations
settings UI. Each connector subclasses `BaseConnector`, persists its
state inside the existing `Integration.config` JSONB (no new tables),
encrypts every secret at rest via `app/utils/secret_crypto`, and
degrades gracefully when the integration row is missing or
`is_active=False` -- every method returns
`{"ok": false, "error": "Integration not configured"}` without
raising, so the timer, exports, and dashboards keep working when a
connector is disabled or broken.
All third-party HTTP calls go through `requests` with a 10-second
timeout and a `try/except requests.RequestException`. Tokens are
never written to logs in their raw form -- only short
`xoxb-...` / `ghp_...` truncations.
GitHub connector (`app/integrations/github_connector.py`, provider
key `github_connector`):
- Webhook receiver at `POST /api/integrations/github/webhook`
verifies `X-Hub-Signature-256` with HMAC-SHA256 against the
per-integration webhook secret before reading the payload.
- Handles `issues.opened` (creates a task with
`external_ref="github_issue_{n}"`, mapped priority and `todo`
status), `issues.assigned` (optionally starts a timer for the
linked TimeTracker user when `users.github_username` matches),
`issues.closed` (marks the existing task `done`), and `ping`.
- Manual sync (`POST /api/integrations/github/sync`, admin only)
pulls open issues from
`GET /repos/{owner}/{repo}/issues?state=open&per_page=50` and
upserts tasks by `external_ref`. Optional `label_filter`.
Google Calendar connector (`app/integrations/google_calendar_connector.py`,
provider key `google_calendar_connector`):
- OAuth2 flow at `/integrations/google/{connect,callback,disconnect}`
using raw `requests` against
`https://oauth2.googleapis.com/token`. Tokens (`access_token`,
`refresh_token`, `token_expiry`) are stored encrypted in
`Integration.config`. `client_id`/`client_secret` come from
Flask config (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`) and are
never hardcoded.
- `_refresh_token_if_needed()` refreshes within 5 minutes of expiry
on every API call.
- `sync()` supports `import` / `export` / `both`:
* import: pulls dated events from the configured `calendar_id`
over the last `sync_days_back` days (clamped 1-30), skips
all-day events and anything tagged `[TT]` or already linked via
`gcal:{event_id}` in the notes of an existing `TimeEntry`.
* export: posts completed entries created since `last_sync_at`
back to Google as `[TT] {project} -- {task or notes}` events
with `timeZone: "UTC"`.
- `revoke()` calls `https://oauth2.googleapis.com/revoke` and
wipes the stored tokens.
- APScheduler job `google_calendar_sync` runs every 30 minutes;
each user is wrapped in `try/except` so one broken token cannot
block the rest.
Slack connector (`app/integrations/slack_connector.py`, provider key
`slack_connector`):
- Webhook receiver at `POST /api/integrations/slack/events`
verifies `X-Slack-Signature` (HMAC-SHA256 of
`v0:{timestamp}:{body}`) and rejects requests older than 5
minutes. Replies to Slack's URL verification handshake
immediately.
- Slash command `/tt` supports `start [project]` (id or
case-insensitive partial name match against the user's allowed
projects), `stop`, `status`, `today` (via
`notification_service.get_today_summary_for_user`), and an
in-place help text fallback. Every reply is ephemeral JSON so it
fits inside Slack's 3-second budget without touching
`response_url`.
- `notify_timer_started` / `notify_timer_stopped` post a
stopwatch/checkmark message to the configured channel. Wired
into both the page route (`app/routes/timer.py`) and the JSON
API (`app/routes/api.py`) as a fire-and-forget hook: the import
+ call are wrapped in `try/except` and only log at `DEBUG` on
failure, so Slack outages can't slow down the timer flow.
- `post_daily_summary` posts a daily roll-up; APScheduler job
`slack_daily_summary` runs every 30 minutes and matches each
user's configured `HH:MM` against the window.
Plumbing and storage:
- New blueprint `app/routes/integrations_webhooks.py` registers
the webhook receivers (`csrf.exempt`, signature-verified) plus a
uniform `config`/`status`/`test` API surface
(`/api/integrations/{github,google,slack}/{config,status,test}`)
used by the settings UI. Optional-registered in
`app/blueprint_registry.py`.
- Alembic revision `155_add_integration_columns`:
* `users.github_username` (String(100), nullable) - GitHub login
join key for the assignment auto-start-timer flow.
* `tasks.external_ref` (String(200), nullable, indexed) -
canonical external id for connector-created tasks; the new
index lets webhook receivers de-duplicate cheaply.
Both columns are added defensively (inspector-checked) so the
migration is safe to re-run.
- New cards in `app/templates/integrations/_connector_cards.html`
(included by `templates/integrations/list.html`) drive the
Personal connectors UI -- Tailwind CSS only, vanilla JS, per-card
status fetch, save, test, and sync actions.
Documentation:
- `docs/integrations/README.md` indexes all built-in connectors.
- `docs/integrations/GITHUB_CONNECTOR.md`,
`docs/integrations/GOOGLE_CALENDAR.md`, and
`docs/integrations/SLACK.md` cover setup, OAuth/webhook wiring,
config fields, endpoints, and operational notes for each
connector.
- `docs/api/REST_API.md` lists the new endpoints under a new
"Personal integration connectors" subsection.
- `CHANGELOG.md` notes the feature under the [Unreleased] section.
`LLMService`, `TimeTrackingService`, `ForecastService`, and the
`Integration` model schema are intentionally untouched -- only
`users` and `tasks` gain columns via migration.
Bump setup.py to 5.5.7 and document the invoice PDF designer layout fix,
designer-to-ReportLab template parity, and preview vs export alignment
for issue #622 in CHANGELOG.md.
- Honor AI_ENABLED across session AI, REST v1, LLM service, templates, and
context; add regression tests for the AI helper gate.
- Docker Compose: optional Ollama behind the ai profile; align env.example
and example compose with safe defaults.
- Add UNINSTALL.md with a dedicated AI teardown section; cross-link from
README, INSTALLATION, Getting Started, docs index, and Docker setup guide.
- Record 5.5.6 in CHANGELOG and sync version examples in BUILD_CONFIGURATION;
bump setup.py to 5.5.6.
Move shell layout fixes from [Unreleased] to CHANGELOG [5.5.5].
Sync BUILD_CONFIGURATION.md version code example and setup.py snippet
with setup.py (single source of truth).
Bump package version in setup.py to 5.5.4.
CHANGELOG: document 5.5.4 (full-database restore hardening and backup/restore documentation).
docs/BUILD_CONFIGURATION.md: refresh version-code example and setup.py snippet to 5.5.4 (50504).
- Fix setup.py version string (missing quote).
- Promote CHANGELOG [Unreleased] entries to [5.5.0] (2026-04-27); leave empty [Unreleased].
- Update BUILD_CONFIGURATION.md example version to match setup.py.
Introduce a connection manager (state machine, listeners, offline handling,
token/server binding) with timer start/stop reconciliation helpers. Refactor
app.js to use it and extend the first-run wizard (welcome + server + token).
Add node:test coverage for the manager, timer operations, and an /api/v1/info
integration harness. Rebuild renderer bundle for packaging.
Bump desktop toolchain (electron, electron-builder, esbuild) and Python
package version to 5.3.2 in setup.py.
Quotes (#583):
- Add requires_approval, approval_level, and can_be_sent; wire create form
- Migrations 145 (approval columns) and 146 (quote_items.position)
- Order Quote.items by position; set positions on create/edit/duplicate/API
- Fix view template approval branch (not_required); add web regression test
Invoices / PEPPOL:
- Use the same Factur-X embed and PDF/A-3 normalization for export and
email attachments; Associated File Data + text/xml metadata
- CII/UBL validators, pdfa3, zugferd, and invoice_pdf_postprocess helper
- Bundle compact sRGB ICC (app/resources/icc/); INVOICE_SRGB_ICC_PATH override
- Package data in setup.py; extend PEPPOL_EINVOICING.md and tests
- REST API v1: add deals, leads, contacts, time-entry-approvals (CRUD + approve/reject/cancel/bulk-approve). New scopes and /info entries.
- Standardize API errors: use error_response, forbidden_response, not_found_response in api_v1 (projects + new CRM/approval routes).
- Consolidate templates: move root templates/ into app/templates/, remove ChoiceLoader and legacy root files.
- Version: README/FEATURES_COMPLETE/CHANGELOG/mobile docs reference setup.py as single source (4.19.0); add [4.19.0] changelog entry.
- Docs: SERVICE_LAYER_AND_BASE_CRUD.md, RBAC_PERMISSION_MODEL.md; base_crud_service docstring points to service-layer doc.
- Mark projects_refactored_example, timer_refactored, invoices_refactored as REFERENCE ONLY in docstrings.
Performance:
- Fix N+1 queries in reports.py with joinedload for TimeEntry.project,
TimeEntry.user, TimeEntry.task, and Project.client across 6 query locations
- Replace per-task time_entries loops with batch UPDATE queries in tasks.py
- Use efficient subquery for favorite project IDs in projects.py
Architecture:
- Add get_by_id() and get_by_name() methods to ProjectService and ClientService
- Route project/client lookups through service layer in timer.py, projects.py,
and clients.py instead of direct Model.query calls
Security:
- Add sanitize_input() with length limits to form inputs in clients.py,
projects.py, timer.py, issues.py, and auth.py
- Add email format validation for client creation
- Warn at startup when SECRET_KEY uses the default value or is too short
in ProductionConfig
- Replace 7 bare except: pass clauses with specific exception types
(OSError, IOError, TypeError, ValueError) in admin.py, settings.py,
and invoice.py
Authorization:
- Migrate all @admin_required decorators to @admin_or_permission_required()
with granular permissions (manage_roles, manage_kanban, manage_webhooks,
manage_api_tokens, manage_integrations, access_admin) across permissions.py,
kanban.py, webhooks.py, and admin.py (28 routes total)
Frontend:
- Remove 40+ console.log debug statements across 18 JS files
- Replace 42 inline onclick/onchange handlers in base.html with delegated
event listeners using data-dropdown and data-no-propagation attributes
- Migrate 6 inline handlers in time_entries_overview.html to addEventListener
- Extract shared typing detection into typing-utils.js, eliminating 5
duplicate isTyping() implementations across keyboard shortcut files
- Add missing aria-label attributes to icon-only buttons
Dependencies:
- Migrate from pytz to stdlib zoneinfo (Python 3.9+) across all 6 files
that used pytz; replace pytz with tzdata in requirements.txt
- Separate dev/test dependencies into requirements-dev.txt
- Configure RotatingFileHandler (10MB, 5 backups) for app and JSON logs
Co-authored-by: Cursor <cursoragent@cursor.com>
Dries Peeters