# 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, only public events included
  - `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.
- 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.