Countdown Events

Display upcoming special events on your home screen with AI-generated whimsical messages. Perfect for birthdays, holidays, vacations, and other family milestones.

Overview

The Countdown feature allows you to:

Mark special todos as “countdown events”
Display the earliest upcoming countdown prominently on the home screen
See AI-generated whimsical messages that change daily
View days remaining in a beautiful gradient widget
Quickly navigate to your todo lists by clicking the widget

Creating a Countdown Event

From Todo Lists Page

Navigate to Todo Lists page
Create a new todo or edit an existing one
Set a due date for the event
Check the “Mark as Countdown Event” checkbox
Save the todo

The countdown will now appear on the home screen if it’s the earliest upcoming countdown event with a future due date.

Requirements

The todo must have a due date set
The due date must be today or in the future
The todo must not be completed
The isCountdown field must be set to true

Home Screen Display

The countdown widget features:

Gradient Background - Beautiful purple-to-pink gradient
Event Name - Large, bold display of the event title
Days Remaining - Huge number showing countdown
- Shows “TODAY” if the event is today
- Shows number of days for future events
AI Message - Whimsical, family-friendly message (if Gemini API is configured)

Visibility

The countdown widget is displayed when:

The countdown feature is enabled in Settings
At least one countdown event exists
The earliest countdown has a due date today or in the future

To toggle the widget:

Go to Settings → Home Screen
Toggle “Countdown” under Visible Widgets

AI-Generated Messages

Gemini Integration (Optional)

Countdown messages can be generated using Google Gemini 1.5 Flash (free tier):

Creative Messages - Whimsical, family-friendly messages
Context-Aware - Different messages for “today”, “tomorrow”, and future dates
Daily Refresh - Messages regenerate every 24 hours
Automatic Caching - Reduces API calls

Setup Gemini API (Optional)

Visit Google AI Studio
Create a free API key
Add to your .env file:
```
NUXT_GEMINI_API_KEY=your_api_key_here
```
Restart Skylite UX

Fallback Messages

If Gemini is not configured, the system uses simple fallback messages:

Today: “Today is the day! [Event] is here!”
Tomorrow: “Only 1 day until [Event]!”
Future: “Only X days until [Event]!”

Message Caching

How It Works

Messages are cached for 24 hours after generation
Cached messages are stored in the database with the todo
Widget refreshes use cached messages when available
New messages generate automatically after 24 hours

Benefits

Reduces API calls to Gemini (respects free tier limits)
Faster page loads (no API waiting time)
Still provides daily variety

Manual Refresh

To force a new message generation:

Wait 24 hours for automatic refresh
Or update the todo (which clears the cache)

The countdown widget refreshes based on your Home Screen settings:

Go to Settings → Home Screen
Adjust Data Refresh Interval (default: 6 hours)
The countdown widget will refresh at this interval

Note: Even with frequent refreshes, AI messages only regenerate once per 24 hours to reduce API usage.

Multiple Countdowns

Priority Display

If you have multiple countdown events:

Only the earliest upcoming event is displayed on the home screen
Events are automatically sorted by due date
Completed events are excluded
Past events are excluded

Managing Multiple Events

Create as many countdown todos as you like
All active countdowns are tracked
The widget automatically updates when dates change
Completing a countdown reveals the next one

Examples

Birthday Countdown

Title: "Emma's 10th Birthday"
Due Date: March 15, 2026
isCountdown: ✓ Yes

Home Display:
┌─────────────────────────────┐
│  Emma's 10th Birthday       │
│                             │
│         42                  │
│      days to go             │
│                             │
│ "The party planning can     │
│  officially begin! 🎉"      │
└─────────────────────────────┘

Vacation Countdown

Title: "Disney World Trip"
Due Date: July 20, 2026
isCountdown: ✓ Yes

Home Display (when tomorrow):
┌─────────────────────────────┐
│    Disney World Trip        │
│                             │
│          1                  │
│       day to go             │
│                             │
│ "Pack those bags and get    │
│  ready for magic! ✨"       │
└─────────────────────────────┘

Event Day

Title: "First Day of School"
Due Date: Today
isCountdown: ✓ Yes

Home Display:
┌─────────────────────────────┐
│   First Day of School       │
│                             │
│        TODAY                │
│                             │
│                             │
│ "Rise and shine! Today's    │
│  the big day! 📚"          │
└─────────────────────────────┘

Technical Details

Database Fields

Each todo has three countdown-specific fields:

isCountdown (Boolean) - Marks the todo as a countdown event
countdownMessage (String, nullable) - Cached AI-generated message
messageGeneratedAt (DateTime, nullable) - When the message was last generated

API Endpoints

GET /api/todos/countdowns - Fetch all active countdown events
POST /api/ai/generate-countdown-message - Generate a new AI message

Performance

Messages cached in database for 24 hours
Widget refreshes use cached data when available
Minimal API calls to Gemini (1 per event per day maximum)

Troubleshooting

Check:

Is the countdown feature enabled in Settings?
Do you have at least one countdown todo?
Does the countdown have a due date set?
Is the due date today or in the future?
Is the todo marked as not completed?

No AI Messages