Module msgraph 

Microsoft Graph backends for the non-Apple platforms (car#520).

macOS binds Calendar/Contacts/Mail to the OS accounts via EventKit / Contacts / Mail automation. On Windows (and Linux) this module talks to Microsoft Graph over REST instead, authenticated with the OAuth 2.0 device-code flow (no embedded browser, works headless).

Configuration (the one external prerequisite)

Graph requires an Azure AD app registration — a public client with the delegated scopes Contacts.Read, Calendars.ReadWrite, Mail.ReadWrite, Mail.Send, offline_access (read-write since car#531 adds event create/update/delete and mail send). Supply its client id via CAR_MSGRAPH_CLIENT_ID (and, optionally, a tenant via CAR_MSGRAPH_TENANT, default common). A cached access token may be provided directly via CAR_MSGRAPH_TOKEN for headless use; otherwise device_code_login performs the interactive flow.

Everything in this module is a pure REST/JSON mapping — the request builders and response parsers are unit-tested; only the network hop needs the live app registration + a signed-in Microsoft account.

Structs

DeviceCode

Parsed device-code response the user acts on.

Enums

GraphError

Constants

CLIENT_ID_ENV

Env var holding the Azure AD app (client) id.

TENANT_ENV

Env var overriding the tenant (common | organizations | consumers | a tenant id). Default common.

TOKEN_ENV

Env var supplying a ready access token (skips the device-code flow).

Functions

contacts

Contacts from Graph (/me/contacts), optionally filtered by a substring.

create_event

Create an event (POST /me/events) → the created Event.

delete_event

Delete an event (DELETE /me/events/{id}).

device_code_login

Run the device-code login: request a code, print instructions, poll until the user authorizes (or it expires). Returns the access token. Requires CLIENT_ID_ENV. sleep is injected so the polling loop is deterministic in tests; production passes std::thread::sleep.

events

Calendar events in [start, end) from Graph (/me/calendarView).

inbox_summary

Inbox unread/total for the signed-in account (/me/mailFolders/inbox).

is_configured

True when a client id or a direct token is configured — the signal the per-OS backends use to decide “Graph” vs. “pending”.

send_mail

Send (POST /me/sendMail) or draft (POST /me/messages, draft_only) mail. Returns the draft message id when drafting; None when sent (sendMail is a 202 with no body).

update_event

Update an event (PATCH /me/events/{id}) → the updated Event.