# Calendar Integrations

## Scope
FieldOps Cloud now has a two-way calendar integration foundation for:

- Google Calendar
- Outlook / Microsoft 365 Calendar

The current implementation is a safe UI and data-contract foundation. It does not request live OAuth tokens, register webhooks, or create/update real calendar events yet.

## Supported Data Flows
- FieldOps scheduled jobs create or update external calendar events.
- External calendar changes can update linked FieldOps job schedules after inbound sync.
- Cancelled or deleted external events can queue FieldOps review actions.
- Linked event records store provider event ids, etags/change keys, hashes, and conflict state.
- Webhook notification records store non-sensitive identifiers and payload hashes.

## Provider Notes
- Google Calendar: use Calendar API incremental sync with `nextSyncToken` for inbound changes, and Events `watch` push channels for notification prompts. Official docs: `https://developers.google.com/workspace/calendar/api/guides/sync` and `https://developers.google.com/workspace/calendar/api/guides/push`.
- Outlook / Microsoft 365 Calendar: use Microsoft Graph calendar-view delta queries for inbound changes and Graph subscriptions for change notifications. Official docs: `https://learn.microsoft.com/en-us/graph/delta-query-events` and `https://learn.microsoft.com/en-us/graph/api/resources/subscription?view=graph-rest-1.0`.

## Database Contracts
- `calendar_connections`: tenant-scoped OAuth connection metadata, encrypted token placeholders, sync tokens/delta links, webhook ids, and last sync timestamps.
- `calendar_event_links`: maps FieldOps jobs to external events with provider ids, etags/change keys, last-synced hashes, and conflict status.
- `calendar_sync_jobs`: retryable inbound/outbound sync queue with idempotency keys.
- `calendar_webhook_events`: non-sensitive webhook notification audit trail using payload hashes.

## Security Requirements
- Require `view_calendar_integrations` for read-only calendar integration visibility.
- Require `manage_calendar_integrations` for future connect, disconnect, and sync configuration actions.
- Encrypt access and refresh tokens before storing them.
- Never log access tokens, refresh tokens, OAuth authorization codes, raw webhook payloads, invite bodies, or customer personal data.
- Scope every calendar connection, event link, webhook event, and sync job by `tenant_id`.
- Validate OAuth `state` values against tenant, user, session, provider, and redirect intent.
- Validate webhook channel tokens or client-state secrets before queueing inbound sync.
- Queue conflicts when FieldOps and the provider changed the same event since the last sync.
- Use idempotency keys for every outbound event create/update/delete operation.

## Next Build Steps
1. Add OAuth authorization and callback controllers for Google and Microsoft.
2. Add encrypted secret storage using an app key from environment.
3. Add webhook receiver endpoints with provider-specific verification.
4. Add background sync workers for full sync, incremental sync, outbound job push, and webhook-triggered refresh.
5. Add a conflict-resolution screen before overwriting schedules.
6. Add sandbox tests after Google Cloud and Microsoft Entra app credentials are available.