# Microsoft Outlook Calendar Events

## Objective

Create and update Microsoft 365 calendar events on the right mailbox and time zone.

A per-user Microsoft 365 calendar connection that writes and updates events on the correct tenant, mailbox, and calendar.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Authorize per user and record which tenant and mailbox the connection belongs to. A user with both a personal and a work account will otherwise have events land in whichever one was authorized most recently.
2. Let the user pick the target calendar within the chosen mailbox at setup, including shared and delegated calendars they hold write access to, and store that choice with the connection.
3. Use the provider's concurrency control on every update: read the current version marker, send it with the change, and treat a mismatch as someone else having edited the event. Re-read and present the conflict rather than overwriting.
4. Attach online meeting details only when the account is licensed for it and the connection was granted the permission. Detect the absence and fall back to a plain event with the app's own link rather than failing the whole create.
5. This brief owns the Microsoft side only. If Google Calendar Event Creation is also present, both must write through one shared calendar-sync abstraction on the record — the record holds one provider reference and one sync state, not two competing ones.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Multi-account users and multi-tenant organizations make the destination ambiguous. Record the tenant, mailbox, and calendar with the connection, show them on the record, and force a re-selection if any of them stops being valid.
- Delegated access and shared mailboxes can be granted and revoked by an administrator at any time. Check write access before each batch, and when it disappears mark the connection as needing attention instead of retrying a permanently rejected call.
- Online meeting creation depends on licensing and consent that the app cannot assume. Create the meeting link only when both are present, and otherwise produce the event without it and tell the user why.
- Two updates racing — one from the app, one from the user in Outlook — will otherwise silently clobber each other. Send the provider's change key or equivalent with every update and treat a rejection as a conflict to resolve, not an error to retry blindly.
- An event deleted or moved directly in Outlook leaves the app's copy stale. Reconcile on the next sync, mark the record as diverged, and offer to recreate or unlink rather than rewriting the user's calendar without asking.
- Times must carry an explicit named time zone, not a fixed offset, or recurring events shift by an hour across a daylight saving boundary and appear correct in the app while being wrong in the calendar.
- Tokens expire and administrators revoke consent for the whole tenant at once. Refresh ahead of expiry, and on tenant-wide revocation disconnect every affected connection with a single clear explanation rather than a flood of individual failures.
- Microsoft throttles aggressively per mailbox. Honour the retry delay it returns, back off with jitter, and bound how many events one bulk action may create before it is spread across a longer window.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] The connection records tenant, mailbox, and calendar, and the user selects the calendar explicitly.
- [ ] Delegated and shared-mailbox permissions are checked, and their loss marks the connection as needing attention.
- [ ] Online meeting details are added only when licensing and consent allow, with a stated fallback otherwise.
- [ ] Every update sends the provider's concurrency marker, and a mismatch is surfaced as a conflict rather than overwritten.
- [ ] Event times carry an explicit named time zone.
- [ ] Events changed or deleted in Outlook are reconciled and flagged on the linked record.
- [ ] Throttling responses are honoured and bulk creates are paced rather than burst.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.