How to Enable and Configure the Vacay Vacation Planner Addon in TREK

Administrators activate Vacay from the Admin → Add-ons page, after which users configure yearly entitlements, public holidays, and collaboration settings through the Vacay UI.

TREK treats Vacay as a global add-on—a feature not tied to any single trip but available to every user once the admin turns it on. The addon provides a yearly calendar, public-holiday lookup, company-holiday layers, carry-over handling, and the ability to fuse plans with other TREK users. Once enabled, Vacay integrates directly into the main navigation and exposes REST endpoints for programmatic access.

Enabling the Vacay Addon (Admin Setup)

Before users can track vacation days, an administrator must activate the addon globally.

1. Navigate to Admin → Add-ons in the TREK dashboard.
2. Locate the Vacay row under Global add-ons (enabled by default) and toggle the switch if it is off.
3. The change applies instantly, triggering a success toast, and the Vacay entry appears in the main navigation for every user.

According to the repository documentation in wiki/Admin-Addons.md, this single toggle makes the feature available across the entire instance without per-trip configuration.

Accessing the Vacay Interface

Once enabled, users access the planner through the Vacay entry in the left-hand navigation.

The first time a user opens the page, TREK automatically creates a personal plan for that account. The interface immediately displays the current year’s calendar alongside an entitlement panel showing Entitlement days, Used, Remaining, and Carry-over values. A year selector in the sidebar allows switching between calendar years.

Configuring Core Vacation Settings

Click the gear icon in the Vacay UI to open the settings panel. Configuration options are stored per-user and affect how days are calculated and displayed.

Year Plans and Entitlements

Each calendar year operates as a separate panel. The entitlement panel tracks your total allowance against used days, showing remaining balance and any carry-over from previous years. Use the year selector in the sidebar to switch between active plans.

Weekend Blocking and Week Start

Set your calendar preferences to match local norms:

• Block weekends – Prevent logging vacation on selected weekend days.
• Week start – Choose Monday or Sunday as the first day of the week.

These settings affect the visual calendar grid and validation rules when toggling entries.

Carry-Over Handling

Enable the Carry-over toggle to automatically roll unused days into the next calendar year. When active, TREK calculates remaining entitlements across year boundaries and updates the Carry-over display in the entitlement panel.

Public and Company Holidays

Configure automatic holiday layers:

• Public holidays – Add country or region calendars (data fetched from the Nager.at API) to gray out non-working days automatically.
• Company holidays – Enable a shared company-holiday layer that appears for all users but does not deduct from personal allowances.

These configurations are documented in wiki/Vacay.md under the Settings section.

Setting Up Collaborative Plans

Vacay supports fused plans where multiple users can view and manage each other's time-off.

Use the + button in the Persons panel to invite another TREK user by email. Once the invite is accepted, both users see each other’s logged days in distinct colors and can log days on each other’s behalf. To separate plans again, use the Dissolve action in Settings.

This collaboration feature is implemented in the Vacay addon logic and documented in wiki/Vacay.md.

API Endpoints and Schema Validation

The Vacay addon exposes REST-style endpoints under the vacay scope, allowing external tools and MCP (Model Context Protocol) integrations to interact with calendar data.

Key Endpoints

# Full snapshot of the active vacation plan (members, years, config)

curl -H "Authorization: Bearer $TOKEN" \
     "$APP_URL/trek/api/addons/vacay/plan"

# All entries for a specific year (e.g., 2025)

curl -H "Authorization: Bearer $TOKEN" \
     "$APP_URL/trek/api/addons/vacay/entries/2025"

# Public holidays for a year/region (e.g., DE-BY, 2025)

curl -H "Authorization: Bearer $TOKEN" \
     "$APP_URL/trek/api/addons/vacay/holidays/2025?region=DE-BY"

These endpoints are listed in wiki/MCP-Addon-Tools.md.

Zod Schema Validation

All incoming requests are validated against Zod schemas defined in shared/src/vacay/vacay.schema.ts:

• vacayAddHolidayCalendarRequestSchema – Validates public holiday calendar additions.
• vacayToggleEntryRequestSchema – Validates create/remove day entry operations.
• vacayInviteRequestSchema – Validates collaboration invites.

Programmatic Examples

Toggle a vacation day from a React component:

import { api } from '@/utils/api';
import { formatISO } from 'date-fns';

function toggleDay(date: Date) {
  const payload = { date: formatISO(date, { representation: 'date' }) };
  api.post('/api/addons/vacay/toggle', payload).then(() => {
    // UI auto-refreshes via WebSocket (vacay:update)
  });
}

Invite a user to share your plan:

function inviteUser(email: string) {
  api.post('/api/addons/vacay/invite', { user_id: email }).then(() => {
    alert('Invitation sent!');
  });
}

Summary

• Enable globally via Admin → Add-ons in wiki/Admin-Addons.md; changes apply instantly.
• Automatic provisioning creates personal plans on first access; no manual setup required.
• Settings control weekends, week start, carry-over, and holiday layers (public vs. company).
• Collaboration allows fused plans with shared logging and distinct color coding.
• API access via /trek/api/addons/vacay/* endpoints with Zod validation in shared/src/vacay/vacay.schema.ts.

Frequently Asked Questions

How do I enable the Vacay vacation planner addon in TREK?

Administrators navigate to Admin → Add-ons, locate Vacay under Global add-ons, and toggle the switch to on. The change is immediate, and the Vacay navigation item appears for all users instantly.

Can unused vacation days carry over to the next year?

Yes. Enable the Carry-over toggle in the Vacay settings panel. When active, TREK automatically calculates remaining entitlement days and rolls them into the next calendar year’s balance.

How do I share my vacation plan with a colleague?

Click the + button in the Persons panel and enter the colleague’s email. Once they accept the invitation, both users see each other’s logged days in different colors and can log time on behalf of one another. Use the Dissolve action in Settings to separate plans later.

Where are the API schemas for Vacay defined?

All Zod validation schemas reside in shared/src/vacay/vacay.schema.ts. This file contains vacayAddHolidayCalendarRequestSchema, vacayToggleEntryRequestSchema, and vacayInviteRequestSchema, which validate requests to the /trek/api/addons/vacay/* endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}