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.

GraphNamed

A named Graph object with an id — a OneNote notebook or a To Do list.

GraphNote

A OneNote page summary.

GraphTask

A Microsoft To Do task.

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”.

mail_folders

Every mail folder of the signed-in account (/me/mailFolders plus a bounded childFolders walk), nested ones included.

message_body

One message’s body (/me/messages/{id}?$select=body).

messages

Message rows from one folder (/me/mailFolders/{id}/messages).

onenote_notebooks

OneNote notebooks (/me/onenote/notebooks) — the “accounts” for notes.

onenote_pages

OneNote pages (/me/onenote/pages), newest first, optionally filtered by a case-insensitive title substring (client-side, mirroring contacts).

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).

todo_lists

Microsoft To Do lists (/me/todo/lists).

todo_tasks

Microsoft To Do tasks across all lists (/me/todo/lists/{id}/tasks), up to limit (0 = no cap). Tasks are per-list in Graph, so this fans out; one list failing (transient error) drops only that list, not the whole result.

update_event

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