calendar-plugin/requirements/ics_endpoint.md

ICS Endpoint Requirements

Purpose

Define the ICS endpoint path, visibility model, caching behavior, and synchronization expectations.

Scope

This document covers:

• ICS endpoint routing and response contract
• Public vs authenticated access policy
• Caching/refresh behavior
• Multi-calendar considerations

Normative Boundaries

• This document is authoritative for ICS endpoint path/access/cache behavior.
• ICS payload formatting and field mapping are defined in requirements/ics.md.
• Recurrence exception export behavior is defined in requirements/recurrence_exceptions.md.
• Authorization policy integration is defined in requirements/authorization.md.
• Error normalization is defined in requirements/error_model.md.

Endpoint Contract

• Default endpoint path: /calendar.ics
• If url_slug is configured in setup, canonical endpoint path is /<url_slug>/calendar.ics.
• Alternative implementation path may be used if documented; one canonical URL must be exposed in UI.
• Response content type: text/calendar; charset=utf-8

Access Policy

• Access mode is configurable in Setup:
  • public_read: endpoint accessible without auth; includes both public and private events, with private events redacted
  • authenticated_read: endpoint requires authenticated access
• Default mode: public_read unless overridden by policy requirements.

Data Scope

• ICS output includes only events intended for the selected endpoint audience.
• Internal/admin-only metadata must never appear in output.
• In public_read mode, private events remain in timeline position but expose only date/time and the title Private Event.
• Recurrence and exception semantics follow requirements/ics.md and requirements/recurrence_exceptions.md.

Stability and Subscription

• Endpoint URL should remain stable for long-lived subscriptions.
• If URL must change, documented migration/redirection behavior is required.

Caching and Freshness

• Responses should include deterministic cache headers.
• ETag and/or Last-Modified should be emitted where practical.
• Cache policy must balance freshness and performance for subscriber clients.

Failure Behavior

• On generation failure, return a clear HTTP error status and log details.
• Endpoint must not return malformed partial ICS payload.

Multi-Calendar Support

• First pass supports single canonical calendar feed.
• If multiple feeds are added later, each feed requires stable URL and explicit audience rules.

Verification Requirements

Acceptance should verify:

• Canonical ICS URL is discoverable from web UI.
• Access policy mode is enforced correctly.
• Payload is valid and subscriber-compatible.
• ETag/Last-Modified behavior supports efficient refresh checks.