feat: add calendar subscription token functionality and ICS generation

- Introduced a new database model for calendar subscription tokens, allowing users to generate unique tokens for accessing their personal calendar.
- Implemented API endpoint to return ICS files containing only the subscribing user's duties, enhancing user experience with personalized calendar access.
- Added utility functions for generating ICS files from user duties, ensuring proper formatting and timezone handling.
- Updated command handlers to support the new calendar link feature, providing users with easy access to their personal calendar subscriptions.
- Included unit tests for the new functionality, ensuring reliability and correctness of token generation and ICS file creation.

duty_teller/api/app.py

@@ -1,10 +1,12 @@
 """FastAPI app: /api/duties and static webapp."""
 
 import logging
+from datetime import date, timedelta
 
 import duty_teller.config as config
 from fastapi import Depends, FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import Response
 from fastapi.staticfiles import StaticFiles
 from sqlalchemy.orm import Session
 
@@ -15,6 +17,8 @@ from duty_teller.api.dependencies import (
     get_validated_dates,
     require_miniapp_username,
 )
+from duty_teller.api.personal_calendar_ics import build_personal_ics
+from duty_teller.db.repository import get_duties_for_user, get_user_by_calendar_token
 from duty_teller.db.schemas import CalendarEvent, DutyWithUser
 
 log = logging.getLogger(__name__)
@@ -57,6 +61,31 @@ def list_calendar_events(
     return [CalendarEvent(date=e["date"], summary=e["summary"]) for e in events]
 
 
+@app.get("/api/calendar/ical/{token}.ics")
+def get_personal_calendar_ical(
+    token: str,
+    session: Session = Depends(get_db_session),
+) -> Response:
+    """
+    Return ICS calendar with only the subscribing user's duties.
+    No Telegram auth; access is by secret token in the URL.
+    """
+    user = get_user_by_calendar_token(session, token)
+    if user is None:
+        return Response(status_code=404, content="Not found")
+    today = date.today()
+    from_date = (today - timedelta(days=365)).strftime("%Y-%m-%d")
+    to_date = (today + timedelta(days=365 * 2)).strftime("%Y-%m-%d")
+    duties_with_name = get_duties_for_user(
+        session, user.id, from_date=from_date, to_date=to_date
+    )
+    ics_bytes = build_personal_ics(duties_with_name)
+    return Response(
+        content=ics_bytes,
+        media_type="text/calendar; charset=utf-8",
+    )
+
+
 webapp_path = config.PROJECT_ROOT / "webapp"
 if webapp_path.is_dir():
     app.mount("/app", StaticFiles(directory=str(webapp_path), html=True), name="webapp")

duty_teller/api/personal_calendar_ics.py

@@ -0,0 +1,57 @@
+"""Generate ICS calendar containing only one user's duties (for subscription link)."""
+
+from datetime import datetime, timezone
+
+from icalendar import Calendar, Event
+
+from duty_teller.db.models import Duty
+
+# Summary labels by event_type (duty | unavailable | vacation)
+SUMMARY_BY_TYPE: dict[str, str] = {
+    "duty": "Duty",
+    "unavailable": "Unavailable",
+    "vacation": "Vacation",
+}
+
+
+def _parse_utc_iso(iso_str: str) -> datetime:
+    """Parse ISO 8601 UTC string (e.g. 2025-01-15T09:00:00Z) to timezone-aware datetime."""
+    s = iso_str.strip().rstrip("Z")
+    if "Z" in s:
+        s = s.replace("Z", "+00:00")
+    else:
+        s = s + "+00:00"
+    return datetime.fromisoformat(s)
+
+
+def build_personal_ics(duties_with_name: list[tuple[Duty, str]]) -> bytes:
+    """
+    Build a single VCALENDAR with one VEVENT per duty.
+    duties_with_name: list of (Duty, full_name); full_name is unused for SUMMARY
+    if we use event_type only; can be used later for DESCRIPTION.
+    """
+    cal = Calendar()
+    cal.add("prodid", "-//Duty Teller//Personal Calendar//EN")
+    cal.add("version", "2.0")
+    cal.add("calscale", "GREGORIAN")
+
+    for duty, _full_name in duties_with_name:
+        event = Event()
+        start_dt = _parse_utc_iso(duty.start_at)
+        end_dt = _parse_utc_iso(duty.end_at)
+        # Ensure timezone-aware for icalendar
+        if start_dt.tzinfo is None:
+            start_dt = start_dt.replace(tzinfo=timezone.utc)
+        if end_dt.tzinfo is None:
+            end_dt = end_dt.replace(tzinfo=timezone.utc)
+        event.add("dtstart", start_dt)
+        event.add("dtend", end_dt)
+        summary = SUMMARY_BY_TYPE.get(
+            duty.event_type if duty.event_type else "duty", "Duty"
+        )
+        event.add("summary", summary)
+        event.add("uid", f"duty-{duty.id}@duty-teller")
+        event.add("dtstamp", datetime.now(timezone.utc))
+        cal.add_component(event)
+
+    return cal.to_ical()

duty_teller/db/models.py

@@ -26,6 +26,19 @@ class User(Base):
     duties: Mapped[list["Duty"]] = relationship("Duty", back_populates="user")
 
 
+class CalendarSubscriptionToken(Base):
+    """One active calendar subscription token per user; token_hash is unique."""
+
+    __tablename__ = "calendar_subscription_tokens"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("users.id"), nullable=False
+    )
+    token_hash: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
+    created_at: Mapped[str] = mapped_column(Text, nullable=False)
+
+
 class Duty(Base):
     __tablename__ = "duties"
 

duty_teller/db/repository.py

@@ -1,10 +1,13 @@
 """Repository: get_or_create_user, get_duties, insert_duty, get_current_duty, group_duty_pins."""
 
-from datetime import datetime, timedelta
+import hashlib
+import hmac
+import secrets
+from datetime import datetime, timedelta, timezone
 
 from sqlalchemy.orm import Session
 
-from duty_teller.db.models import User, Duty, GroupDutyPin
+from duty_teller.db.models import User, Duty, GroupDutyPin, CalendarSubscriptionToken
 
 
 def get_user_by_telegram_id(session: Session, telegram_user_id: int) -> User | None:
@@ -98,6 +101,74 @@ def get_duties(
     return list(q.all())
 
 
+def get_duties_for_user(
+    session: Session,
+    user_id: int,
+    from_date: str,
+    to_date: str,
+) -> list[tuple[Duty, str]]:
+    """Return list of (Duty, full_name) for the given user overlapping the date range."""
+    to_date_next = (
+        datetime.fromisoformat(to_date + "T00:00:00") + timedelta(days=1)
+    ).strftime("%Y-%m-%d")
+    q = (
+        session.query(Duty, User.full_name)
+        .join(User, Duty.user_id == User.id)
+        .filter(
+            Duty.user_id == user_id,
+            Duty.start_at < to_date_next,
+            Duty.end_at >= from_date,
+        )
+    )
+    return list(q.all())
+
+
+def _token_hash(token: str) -> str:
+    """Return SHA256 hex digest of the token (constant-time comparison via hmac)."""
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+def create_calendar_token(session: Session, user_id: int) -> str:
+    """
+    Create a new calendar subscription token for the user.
+    Removes any existing tokens for this user. Returns the raw token string.
+    """
+    session.query(CalendarSubscriptionToken).filter(
+        CalendarSubscriptionToken.user_id == user_id
+    ).delete(synchronize_session=False)
+    raw_token = secrets.token_urlsafe(32)
+    token_hash_val = _token_hash(raw_token)
+    now_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    record = CalendarSubscriptionToken(
+        user_id=user_id,
+        token_hash=token_hash_val,
+        created_at=now_iso,
+    )
+    session.add(record)
+    session.commit()
+    return raw_token
+
+
+def get_user_by_calendar_token(session: Session, token: str) -> User | None:
+    """
+    Find user by calendar subscription token. Uses constant-time comparison.
+    Returns None if token is invalid or not found.
+    """
+    token_hash_val = _token_hash(token)
+    row = (
+        session.query(CalendarSubscriptionToken, User)
+        .join(User, CalendarSubscriptionToken.user_id == User.id)
+        .filter(CalendarSubscriptionToken.token_hash == token_hash_val)
+        .first()
+    )
+    if row is None:
+        return None
+    # Constant-time compare to avoid timing leaks (token_hash is already hashed).
+    if not hmac.compare_digest(row[0].token_hash, token_hash_val):
+        return None
+    return row[1]
+
+
 def insert_duty(
     session: Session,
     user_id: int,

duty_teller/handlers/__init__.py

@@ -9,6 +9,7 @@ def register_handlers(app: Application) -> None:
     app.add_handler(commands.start_handler)
     app.add_handler(commands.help_handler)
     app.add_handler(commands.set_phone_handler)
+    app.add_handler(commands.calendar_link_handler)
     app.add_handler(import_duty_schedule.import_duty_schedule_handler)
     app.add_handler(import_duty_schedule.handover_time_handler)
     app.add_handler(import_duty_schedule.duty_schedule_document_handler)

duty_teller/handlers/commands.py

@@ -7,7 +7,11 @@ from telegram import Update
 from telegram.ext import CommandHandler, ContextTypes
 
 from duty_teller.db.session import session_scope
-from duty_teller.db.repository import get_or_create_user, set_user_phone
+from duty_teller.db.repository import (
+    get_or_create_user,
+    set_user_phone,
+    create_calendar_token,
+)
 from duty_teller.i18n import get_lang, t
 from duty_teller.utils.user import build_full_name
 
@@ -82,6 +86,55 @@ async def set_phone(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         await update.message.reply_text(t(lang, "set_phone.cleared"))
 
 
+async def calendar_link(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Send personal calendar subscription URL (private chat only, access check)."""
+    if not update.message or not update.effective_user:
+        return
+    lang = get_lang(update.effective_user)
+    if update.effective_chat and update.effective_chat.type != "private":
+        await update.message.reply_text(t(lang, "calendar_link.private_only"))
+        return
+    telegram_user_id = update.effective_user.id
+    username = (update.effective_user.username or "").strip()
+    full_name = build_full_name(
+        update.effective_user.first_name, update.effective_user.last_name
+    )
+
+    def do_calendar_link() -> tuple[str | None, str | None]:
+        with session_scope(config.DATABASE_URL) as session:
+            user = get_or_create_user(
+                session,
+                telegram_user_id=telegram_user_id,
+                full_name=full_name,
+                username=update.effective_user.username,
+                first_name=update.effective_user.first_name,
+                last_name=update.effective_user.last_name,
+            )
+            if not config.can_access_miniapp(
+                username
+            ) and not config.can_access_miniapp_by_phone(user.phone):
+                return (None, "denied")
+            token = create_calendar_token(session, user.id)
+            base = (config.MINI_APP_BASE_URL or "").rstrip("/")
+            url = f"{base}/api/calendar/ical/{token}.ics" if base else None
+            return (url, None)
+
+    result_url, error = await asyncio.get_running_loop().run_in_executor(
+        None, do_calendar_link
+    )
+    if error == "denied":
+        await update.message.reply_text(t(lang, "calendar_link.access_denied"))
+        return
+    if not result_url:
+        await update.message.reply_text(t(lang, "calendar_link.error"))
+        return
+    await update.message.reply_text(
+        t(lang, "calendar_link.success", url=result_url)
+        + "\n\n"
+        + t(lang, "calendar_link.help_hint")
+    )
+
+
 async def help_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     if not update.message or not update.effective_user:
         return
@@ -91,6 +144,7 @@ async def help_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         t(lang, "help.start"),
         t(lang, "help.help"),
         t(lang, "help.set_phone"),
+        t(lang, "help.calendar_link"),
         t(lang, "help.pin_duty"),
     ]
     if config.is_admin(update.effective_user.username or ""):
@@ -101,3 +155,4 @@ async def help_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 start_handler = CommandHandler("start", start)
 help_handler = CommandHandler("help", help_cmd)
 set_phone_handler = CommandHandler("set_phone", set_phone)
+calendar_link_handler = CommandHandler("calendar_link", calendar_link)

duty_teller/i18n/messages.py

@@ -11,7 +11,13 @@ MESSAGES: dict[str, dict[str, str]] = {
         "help.start": "/start — Start",
         "help.help": "/help — Show this help",
         "help.set_phone": "/set_phone — Set or clear phone for duty display",
+        "help.calendar_link": "/calendar_link — Get personal calendar subscription link (private chat)",
         "help.pin_duty": "/pin_duty — In a group: pin the duty message (bot needs admin with Pin messages)",
+        "calendar_link.private_only": "The /calendar_link command is only available in private chat.",
+        "calendar_link.access_denied": "Access denied.",
+        "calendar_link.success": "Your personal calendar URL:\n{url}",
+        "calendar_link.help_hint": "Subscribe to this URL in Google Calendar, Apple Calendar, or Outlook to see only your duties.",
+        "calendar_link.error": "Could not generate link. Please try again later.",
         "help.import_schedule": "/import_duty_schedule — Import duty schedule (JSON)",
         "errors.generic": "An error occurred. Please try again later.",
         "pin_duty.group_only": "The /pin_duty command works only in groups.",
@@ -48,7 +54,13 @@ MESSAGES: dict[str, dict[str, str]] = {
         "help.start": "/start — Начать",
         "help.help": "/help — Показать эту справку",
         "help.set_phone": "/set_phone — Указать или очистить телефон для отображения в дежурстве",
+        "help.calendar_link": "/calendar_link — Получить ссылку на персональную подписку календаря (только в личке)",
         "help.pin_duty": "/pin_duty — В группе: закрепить сообщение о дежурстве (нужны права админа у бота)",
+        "calendar_link.private_only": "Команда /calendar_link доступна только в личке.",
+        "calendar_link.access_denied": "Доступ запрещён.",
+        "calendar_link.success": "Ссылка на ваш календарь:\n{url}",
+        "calendar_link.help_hint": "Подпишитесь на эту ссылку в Google Календаре, Календаре Apple или Outlook, чтобы видеть только свои дежурства.",
+        "calendar_link.error": "Не удалось сформировать ссылку. Попробуйте позже.",
         "help.import_schedule": "/import_duty_schedule — Импорт расписания дежурств (JSON)",
         "errors.generic": "Произошла ошибка. Попробуйте позже.",
         "pin_duty.group_only": "Команда /pin_duty работает только в группах.",